Table of Contents
Overview¶
PyPty is a phase retrieval library for near-field and far-field imaging in TEM/STEM. It supports:
- Iterative ptychography
- Direct ptychography (Wigner Distribution Deconvolution)
- Differential phase contrast (DPC)
- Tilt-corrected bright field (tcBF)
- Focal series reconstructions
- LARBED reconstructions
Developed by Anton Gladyshev (AG SEM, Physics Department, Humboldt-Universität zu Berlin).
Installation¶
To create a suitable Python environment for PyPty, you can use conda, mamba, or micromamba. Below are installation instructions using conda.
GPU Installation¶
git clone git@github.com:Anton-Gladyshev/pypty.git
cd pypty
conda env create -f pypty_gpu.yml
conda activate pypty
pip install .[gpu]
CPU Installation¶
git clone git@github.com:Anton-Gladyshev/pypty.git
cd pypty
conda env create -f pypty_cpu.yml
conda activate pypty
pip install .
About this Code¶
Main Purpose¶
The primary function of PyPty is gradient-based phase reconstruction from far-field intensities. This is handled via pypty.iterative.run(). Most other functions are designed to simplify usage of this core function.
A complete list of required arguments for pypty.iterative.run() is available in the custom presets guide.
Logic¶
Most PyPty functions accept a single input dictionary called pypty_params, which typically includes both experimental and reconstruction settings. These experimental parameters are often defined separately in a dictionary called experimental_params (see experiment description).
Once you’ve created a valid pypty_params for one experiment, you can reuse it for others by simply "attaching" new experimental parameters.
PyPty also supports various direct methods and tools for initialization.
Input Format¶
PyPty primarily operates on .h5 files and provides tools to convert from NumPy. The .h5 file should contain a dataset named "data" with a 3D array: one scan axis and two detector axes.
PyPty also accepts 4D Nion-style NumPy arrays (with accompanying JSON metadata).
Output Format¶
By default, PyPty saves all output as .npy files inside an output_folder. The folder structure may look like this:
output_folder
├── cg.npy **overwritable checkpoint for scan grid**
├── cp.npy **overwritable checkpoint for probe**
├── co.npy **overwritable checkpoint for object**
├── checkpoint_obj_epoch_N.npy **checkpoint for object at epoch N**
├── checkpoint_probe_epoch_N.npy **checkpoint for probe at epoch N**
├── checkpoint_positions_epoch_N.npy **checkpoint for scan grid at epoch N**
├── params.pkl **parameter file of your reconstruction**
├── loss.csv **.csv log-file**
├── tcbf **folder with tcBF results**
│ ├── tcbf_image_upsampling_5.npy **upsampled tcBF image_**
│ ├── tcbf_image_N.png **intermediate tcBF image at iteration N in .png format**
│ ├── estimated_shifts_N.npy **Fitted shifts at iteration N in .npy format**
│ ├── aberrations_N.npy **Fitted aberrations (in Angstrom) at iteration N in .npy format**
│ ├── PL_angle_deg.npy **array constaining fitted rotation angles at all iterations in .npy format**
│ ├── aberrations_A.npy **2d array constaining fitted aberrations at all iterations in .npy format**
└── dpc **folder with DPC results**
│ ├── idpc.npy **fft-based dpc phase**
│ ├── iterative_dpc.npy **DPC phase (iterative reconstruction)**
└── wdd **folder with WDD results**
├── object.npy **complex object (WDD ptychography)**
You can also convert an output folder into single Nexus .nxs file via pypty.utils.convert_to_nxs() function.
Examples¶
Example workflows are available in the examples folder on GitHub.
For a quick start, check out the following:
- Full Jupyter Notebook Example — A complete pipeline example
- Step-by-Step Breakdown — Explains key functions and logic
- Direct Methods — For Wigner distribution and other direct approaches
- Custom Presets Guide — For advanced setups
Relevant Literature¶
If you have any questions after reading this guide, the following papers, books and links might explain the working principle of the code:
Multi-slice formalism and the NN-style approach¶
1) Earl J. Kirkland. Advanced Computing in Electron Microscopy
2) W. Van den Broek and C. Koch. General framework for quantitative three-dimensional reconstruction from arbitrary detection geometries in TEM
3) W. Van den Broek and C. Koch. Method for Retrieval of the Three-Dimensional Object Potential by Inversion of Dynamical Electron Scattering
Error metrics:¶
LSQ:¶
4) M. Schloz et al. Overcoming information reduced data and experimentally uncertain parameters in ptychography with regularized optimization
5) M. Du et al. Adorym: a multi-platform generic X-ray image reconstruction framework based on automatic differentiation
Maximum Likelihood (ML):¶
6) P. Thibault and M. Guizar-Sicairos. Maximum-likelihood refinement for coherent diffractive imaging
Compressed LSQ:¶
7) A. Gladyshev et al. Lossy Compression of Electron Diffraction Patterns for Ptychography via Change of Basis
lsq_sqrt and lsq_sqrt2:¶
8) P. Godard et al. (2012). Noise models for low counting rate coherent diffraction imaging
Mixed state formalism:¶
9) P Thibault & A.Menzel Reconstructing state mixtures from diffraction measurements— Flux-preserving formalism (for near-field imaging)
Near-field imaging¶
10) C. Koch A flux-preserving non-linear inline holography reconstruction algorithm for partially coherent electrons
Tilted propagator:¶
11) Earl J. Kirkland. Advanced Computing in Electron Microscopy
12) H. She, J. Cui and R. Yu. Deep sub-angstrom resolution imaging by electron ptychography with misorientation correction
Regularization constaints:¶
13) M. Schloz et al. Overcoming information reduced data and experimentally uncertain parameters in ptychography with regularized optimization
14) A. Gladyshev et al. Lossy Compression of Electron Diffraction Patterns for Ptychography via Change of Basis
Linesearch¶
15) L. Armijo (1966). Minimization of functions having Lipschitz continuous first partial derivatives 16) P. Wolfe (1969). Convergence Conditions for Ascent Methods
BFGS algotithm¶
17) C. G. Broyden (1970). The convergence of a class of double-rank minimization algorithms
18) R. Fletcher (1970). A New Approach to Variable Metric Algorithms
19) D. Goldfarb (1970). A Family of Variable Metric Updates Derived by Variational Means
20) D. F. Shanno (1970). Conditioning of quasi-Newton methods for function minimization
Complex derivatives¶
21) W. Wirtinger (1927). Zur formalen theorie der funktionen von mehr komplexen veränderlichen.
Getting started with the initialize Module¶
PyPty comes with an initialize module (see the API Reference), which is designed specifically for far-field ptychography.
This module makes it easy to:
- Create a calibrated dataset
- Generate a PyPty preset from scratch
If your experimental setup involves additional complexity or non-standard conditions, please refer to the Custom Preset Guide for more flexible configuration.
However, if your setup fits the typical far-field ptychography case, you can summarize all key experimental parameters in a single Python dictionary. For clarity, we usually refer to this as experimental_params.
The dictionary should contain the following keys:
Essential Data Paths¶
| Key | Type | Description |
|---|---|---|
data_path |
str |
Path to a 3D PyPty .h5 dataset ([N_measurements, ky, kx]) or a 4D-STEM .npy dataset. |
masks |
ndarray or None |
If the data is compressed, provide the virtual detectors ([N_masks, ky, kx]). |
output_folder |
str |
Directory where results will be stored. |
path_json |
str |
Path to a Nion-style .json file with metadata (optional). |
Electron Beam Properties¶
| Key | Type | Description |
|---|---|---|
acc_voltage |
float |
Accelerating voltage (in kV). |
rez_pixel_size_A |
float |
Reciprocal pixel size (in Å⁻¹). |
rez_pixel_size_mrad |
float |
Reciprocal pixel size (in mrad). |
conv_semiangle_mrad |
float |
Beam convergence semi-angle (in mrad). |
aperture |
ndarray (optional) |
Binary 2D mask representing the aperture. |
bright_threshold |
float |
Threshold for estimating an aperture. Everything above threshold * max(PACBED) is considered bright field. |
Scan and Positioning¶
| Key | Type | Description |
|---|---|---|
scan_size |
tuple(int, int) |
Number of scan points along slow (y) and fast (x) axes. |
scan_step_A |
float |
Scan step (STEM pixel size) in Å. |
fov_nm |
float |
Field of view (FOV) along the fast axis in nm. |
special_positions_A |
ndarray (optional) |
If data was acquired on a non-rectangular grid, specify positions as [y_0, x_0], ..., [y_n, x_n] (in Å). |
transform_axis_matrix |
ndarray (2×2) |
Transformation matrix for position correction. |
PLRotation_deg |
float or "auto" |
Rotation angle between scan and detector axes. If "auto", an iDPC measurement estimates this angle. |
Reconstruction Settings¶
| Key | Type | Description |
|---|---|---|
num_slices |
int |
Number of slices used for multislice propagation (default: 1). |
total_thickness |
float |
Total thickness of the sample (in Å). |
data_pad |
int or None |
Reciprocal space padding. Default: 1/4 of pattern width. |
upsample_pattern |
int |
Upsampling factor for diffraction patterns. |
flip_ky |
bool |
Flip the y-axis of diffraction patterns. |
defocus |
float |
Extra probe defocus (besides aberrations). |
aberrations |
list or ndarray |
Beam aberrations (stored in Krivanek notation). |
Output & Debugging¶
| Key | Type | Description |
|---|---|---|
plot |
bool |
If True, generates plots of key experimental parameters. |
print_flag |
int |
Controls verbosity (0 = silent, 1 = summary, 2+ = detailed logs). |
save_preprocessing_files |
bool |
If True, saves intermediate preprocessing files. |
Nexus Tags¶
| Key | Type | Description |
|---|---|---|
chemical_fomula |
string |
You can optionally provide a formula for your sample. PyPty will store this information. |
sample_name |
string |
You can optionally provide a name of your sample. PyPty will store this information. |
Breakdown of Examples for Iterative Ptychography¶
This section provides a detailed breakdown of an iterative ptychography reconstruction using PyPty. To get started, create a Python script and import the necessary libraries:
import numpy as np
import pypty
# NumPy is used for minor preprocessing, while all major operations are handled by PyPty.
print("PyPty version: ", pypty._version_)
Normal 4D-STEM iterative ptychography.¶
In this section I will go through the steps required to do a ptychographic reconstruction from normal 4D-STEM data (far-field).
Creation of Calibrated Data¶
In a first step we want to create and center a 4D-STEM dataset (in h5 format). PyPty can also accept raw numpy-arrays, but it's better to do this preprocessing step.
path = path_to_your_data
name = name of your dataset
path_raw = path+name+".npy"
path_h5 = path+name+".h5"
pypty.initialize.create_pypty_data(path_raw, path_h5, swap_axes=False,
flip_ky=0,flip_kx=0, comcalc_len=200*200,
comx=0, comy=0, bin=1, crop_left=None,
crop_right=None, crop_top=None, crop_bottom=None, normalize=False, exist_ok=1)
Experimental parameters¶
PyPty accepts .json metadata from Nion microscopes, but you can also specify all entries yourself. Here I create a dictionary experimental_params with relevant parameters. See the experiment description for further details.
path_json="" ## I will leave this string like this and specify everything by hand.
output_folder=your_output_folder
experimental_params={
'output_folder': output_folder,
'path_json': path_json,
'data_path': path_h5,
### You can specify one of the following three parameters
'rez_pixel_size_A': None,
'rez_pixel_size_mrad': None,
'conv_semiangle_mrad': 33.8,
'scan_size': [256,256], ## this is number of scan points along slow and fast axes
### You can specify one of the following two parameters
'scan_step_A': 0.18, # scan step in Angstrom
'fov_nm': None,
'acc_voltage': 60, ## kV
'aberrations': [200,0,0],## Angstrom [C10, C12a, C12b], can be longer
'PLRotation_deg': 4.65, # deg
'bright_threshold': 0.2, ## this parameter will be used to estimate the aperture
'total_thickness': 6, ## Angstrom, thickness of the sample
'num_slices': 1, ## number of slices in your reconstruction
'plot': True, ## pypty will plot a few things
'print_flag': 3, ## max verbosity
'data_pad': None, ## None will add 1/4 of pixels to each side. This is done to prevent aliasing. You can do any other positive int.
## now there are 2 nexus tags you can specify. This will help to identify your reconstruction in the Future.
'chemical_formula': YOUR_Formula,
'sample_name': NAME_of_YOUR_Sample,
}
Loading a reconstruction preset¶
Parameters for iterative ptychography are stored in a dictionary typically named pypty_params.
1) Such presets are typically stored as .pkl data and you can load them via a function in utils module
2) Alternatively, you can load them from a nexus data of another reconstruction
3) A third option is to construct your custom preset as a dictionary from scratch (Please see the guide ) 4) Finally, you can specify it asNone, then you will have a standard preset
Joining a preset with experimental parameters¶
Once you have a preset, you can add experimental data to it.
Starting Ptychography¶
This is done with a single function and single argument, pypty_params:
Saving your Results as one Nexus file¶
Once your reconstruction is done, you will find a bunch of files in the output_folder. You can stack them into one big nexus file via a single function. You can also select where the .nxs file will be saved via
path_to_your_nexus_file
Reconstruction without an extra h5 file¶
If you do not want to create an extra .h5 file (not recommended), you can specify the 4D-STEM data directly in the experimental parameters (before you join them with pypty_params).
data_path will be ignored and you can leave this field empty. The dataset itself can be either 4D or 3D (with 2 scan axes merged into one).
Iterative Ptychography from Virtual Detectors¶
If you want to perform a reconstruction from data compressed by virtual detectors, you first have to ensure that the array of detectors has shape [N_detectors, k_Y, k_X] and your data has shape [Scan_Y, Scan_X, N_detectors]. Then you attach these two arrays to experimental parameters.
experimental_params={
"dataset": compressed_data,
"masks": virtual_detector_array,
### In this case you must specify one of the following two parameters
'rez_pixel_size_A': None,
'rez_pixel_size_mrad': 1,
# ... Rest of your parameters.
}
| Objective_name | Description |
|---|---|
lsq_compressed |
Least-squared fit |
gauss_compressed |
Gaussian noise model |
poisson_compressed |
Poissonian noise model |
Then you must specify algorithm as one of these three options in pypty_params:
Examples for direct methods¶
This page presents example usage of PyPty’s direct reconstruction methods: Differential Phase Contrast (DPC), Tilt-Corrected Bright Field (tcBF), and Wigner Distribution Deconvolution (WDD). These methods are used when a direct (non-iterative) reconstruction is preferred or as preprocessing for iterative methods.
Differential Phase Contrast (DPC)¶
PyPty is supplied with two functions for differential phase contrast. Both of them aim so solve a Poisson equation, i.e. to reconstruct a phase from its laplacian, gradient of the COM vector field. The first method, based on the Fast Fourier Transform (FFT), reconstructs the phase efficiently and can be executed as follows (including visualization using matplotlib)
dpc_phase, pypty_params= pypty.dpc.fft_based_dpc(pypty_params, hpass=1e-1, lpass=0)
plt.imshow(dpc_phase, cmap="gray")
plt.title("DPC Phase (FFT-based)")
plt.colorbar()
plt.show()
pypty_params, it attempts to automatically calculate them.
Second method is iterative and accounts for non-periodic boundary conditions:
dpc_phase=pypty.dpc.iterative_dpc(pypty_params, num_iterations=100, beta=0.5, hpass=1e-1, lpass=0, step_size=0.1)
plt.imshow(dpc_phase, cmap="gray")
plt.title("DPC Phase (iterative)")
plt.colorbar()
plt.show()
Please see the module description for detailed description of the parameters.
Tilt-Corrected Bright Field (tcBF)¶
In PyPty framework tcBF is done in two steps. First one aims to fit the aberrations of the beam and rotation angle between real and reciprocal spaces by creating an unupsampled tcBF image via run_tcbf_alignment:
pypty_params=pypty.tcbf.run_tcbf_alignment(
pypty_params,
binning_for_fit=np.tile([5], 30),
optimize_angle=True,
cross_corr_type="abs",
refine_box_dim=5,
upsample=10,
cancel_large_shifts=0.9,
reference_type="bf",
tol_ctf=1e-8
)
Note that you have to play with binning values and cross-correlation parameters to get an optimal result. Also, fitted rotation angle typically has a +- pi ambiguity, so if your defocus value comes out with a sign different from the experiment, I suggest to rerun the reconstruction.
A second tcBF function assumes that you already did an alignment and performs an upsampled reconstruction:
tcbf_image,tcbf_px_size = pypty.tcbf.upsampled_tcbf(pypty_params, upsample=3,
pad=10, default_float=32,round_shifts=True)
plt.imshow(tcbf_image, cmap="gray")
plt.title("tcBF image (x3 upsampling)")
plt.colorbar()
plt.show()
Wigner Distribution Deconvolution (WDD)¶
The last direct reconstruction method is Wigner distribution deconvolution (WDD). It is a direct method that reconstructs the object's complex wavefunction by deconvolving the measured intensity distribution with the known probe. WDD requires a calibrated pypty_paramsdictionary containing rotation angle, scan steps and a complex beam (or a set of aberrations). A simple usage example is
obj_wdd=pypty.direct.wdd(pypty_params, eps_wiener=1e-3)
plt.imshow(np.angle(obj_wdd), cmap="gray")
plt.title("WDD Phase")
plt.colorbar()
plt.show()
eps_wiener serves as a regularization term (high-pass filter) to stabilize the deconvolution, preventing division by zero.
Using Direct Methods for Initial Guesses¶
pypty.initialize module is supplied with a function get_ptycho_obj_from_scan that can be used to create complex transmission function based on a measurement sampled at the scan points, this can be a DPC or WDD phase. Usage example is:
pypty_params = pypty.initialize.get_ptycho_obj_from_scan(pypty_params, array_phase=dpc_phase, array_abs=None)
If you have an array on a grid with finer sampling than the actual scan grid of your reconstruction, you may first create an upsampled grid in the image coordinates and use the array for initial guess like this:
image = ## your upsampled image
image_pixel_size = ## pixel size of your image
left_zero_of_scan_grid = # how many pixels of the image are from left of the scan
top_zero_of_scan_grid = # how many pixels of the image are from top of the scan
scan_array_A=pypty.initialize.get_grid_for_upsampled_image(pypty_params, image, image_pixel_size=image_pixel_size, left_zero_of_scan_grid=left_zero_of_scan_grid, top_zero_of_scan_grid=top_zero_of_scan_grid)
pypty_params = pypty.initialize.get_ptycho_obj_from_scan(pypty_params, array_phase=image, array_abs=None, scan_array_A=scan_array_A)
You can also manually specify the initial guess by providing keys like "obj", "probe" or "positions", for more see Guide for creating custom presets.
These direct methods are essential tools in PyPty for rapid insight and as a starting point for more advanced reconstructions. You can combine them with iterative pipelines by injecting results into the initialization phase.
PyPty Parameters for Creating Custom Presets¶
In PyPty, all functions operate using a dictionary that defines your reconstruction setup. This dictionary is typically named pypty_params.
The core function for running iterative ptychographic reconstruction is pypty.iterative.run(), which accepts pypty_params as its single argument.
For simple setups, we recommend using the pypty.initialize module, which helps generate common parameters and arrays automatically. However, for more complex or custom experiments, this guide explains how to construct your own pypty_params dictionary manually.
Lambda-Type Parameters in PyPty¶
Before diving into parameter details, it's important to understand a special type of input PyPty supports: lambda-type parameters.
Because PyPty is iterative, some parameters can be adjusted depending on the current epoch. To do this, use a lambda function that takes the current epoch number as input and returns a value dynamically.
Example¶
To apply the smart_memory flag only every 10 epochs, set it like this:
The parameters that can be written in this way are marked as pypty_lambda type in the Default Data Type column. They can also be specified as a sting containing the code, e.g.
⚠️ Important Note on Lambda Usage
We do not recommend toggling constraints or critical parameters every few epochs. Doing so can interfere with PyPty’s BFGS optimizer, which builds a Hessian matrix based on parameter continuity. Sudden changes can disrupt convergence and lead to suboptimal results.
Instead, design lambda functions so that once a parameter is activated, it remains consistently enabled for the rest of the reconstruction. This ensures smooth optimization behavior and compatibility with the underlying solver.
For example, to enable a parameter starting at epoch 20 and keep it active afterward:
This pattern is ideal for turning on advanced features or constraints after an initialization period without destabilizing the optimization.Full list of paramerers for pypty.iterative.run()¶
Backend Settings¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
backend |
cp |
NumPy-like python module |
Currently not used, but will be a feature in the future. Right now, whenever CuPy is available, it is used as the GPU backend. If no CUDA is detected, NumPy is used as a CPU replacement. We plan to add support for Apple Silicon, but we are waiting for an optimal library to appear. |
default_dtype |
"double" |
str |
Default data type for computations. Another option is "single". |
Dataset¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
data_path |
"" |
str |
Path to the dataset. It can be an .h5 file with a dataset named "data" containing a 3D measurement array (N_measurements, y, x). Another option is a 4D .npy array or a 3D .npy array. |
dataset |
None |
numpy-array or None |
If you don't want to store data on disk, you can attach a numpy-array with your data to the parameters. If it's provided, data_path is ignored. |
masks |
None |
numpy.ndarray or None |
Masks (virtual detectors) used for data compression. For uncompressed data, leave it as None. |
data_multiplier |
1 |
float |
Multiplier for data values. Used to rescale patterns on the fly without modifying the stored dataset. All patterns will be multiplied by this number. |
data_pad |
0 |
int |
Padding applied to data. Use it to pad patterns on the fly without modifying the stored dataset. We recommend setting it to 1/4 of the pattern width for optimal sampling conditions in far-field mode. |
data_bin |
1 |
int |
Binning factor for data. Used to bin patterns on the fly without modifying the stored dataset. All patterns will be binned by this number. |
flip_ky |
False |
bool |
Flag indicating that one has to flip ky. Useful if patterns are flipped and you don’t want to modify the stored dataset. Another option is to create a PyPty-style .h5 dataset. |
data_shift_vector |
[0,0] |
list |
Shift vector (list with two-values) applied to measurements. Used to shift patterns on the fly without modifying the stored dataset. All patterns will be shifted by the specified number of pixels. |
upsample_pattern |
1 |
int |
Upsampling factor. If the beam footprint is larger than the extent (in far-field mode), this allows to artificially upsample the beam in reciprocal space. Experimental feature! Windowing constraints may be required. |
sequence |
None |
list or None or pypty_lambda |
Sequence used in data processing. This is a list indicating the measurements that will be used for iterative refinement. If None, all measurements contribute. This parameter is useful for reconstructions on subscans without creating additional data files. |
use_full_FOV |
True |
bool |
Boolean flag. Only useful if a sequence is provided. If True, the object can accommodate all measurements. If False, the object accommodates only selected measurements. |
Saving and Printing¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
output_folder |
"" |
str |
Path to the folder where output files will be saved. |
save_loss_log |
True |
bool |
Boolean flag. If True, the loss log will be saved as loss.csv. |
epoch_prev |
0 |
int |
Previous epoch count. Useful for restarting a reconstruction. |
save_checkpoints_every_epoch |
False |
bool or int |
Save checkpoints every epoch. If True, checkpoints will be always saved, if it is provided as an integer, checkpoints will be saved every n'th epoch. |
save_inter_checkpoints |
True |
bool or int |
Save intermediate overwritable checkpoints. This will create .npy arrays: co.npy for the object, cp.npy for the probe, cg.npy for the scan grid, ct.npy for the tilts, cs.npy for the static background, and cb.npy for the beam current. If True, checkpoints will be always saved, if it is provided as an integer, checkpoints will be saved every n'th epoch. |
print_flag |
3 |
int |
Print verbosity level: 0 for no printing, 1 for one overwritable line, 2 and 3 for moderate output. 4 gives the most detailed output. |
Experimental Parameters¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
acc_voltage |
60 |
float |
Acceleration voltage in kV. |
aperture_mask |
None |
numpy.ndarray or None |
Mask for the aperture. Can be used for reciprocal probe constaint later (see section constraints). |
recon_type |
"far_field" |
str |
Type of reconstruction. Options: "far_field" or "near_field". |
alpha_near_field |
0.0 |
float |
Alpha parameter for near-field reconstruction & flux preservation. |
defocus_array |
np.array([0.0]) |
numpy.ndarray |
Array of defocus values for near-field measurement. Irrelevant for far-field. It can contain either a single common defocus value for all measurements or individual values for each measurement. Units: Angstroms. |
Cs |
0.0 |
float |
Spherical aberration coefficient. Units: Angstroms. |
Spatial Calibration¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
slice_distances |
np.array([10.0]) |
numpy.ndarray |
Distances between object slices. Units: Angstroms. You can specify a single value common for all slices or provide individual values. |
pixel_size_x_A |
1.0 |
float |
Pixel size in the x-direction (Angstroms). |
pixel_size_y_A |
1.0 |
float |
Pixel size in the y-direction (Angstroms). |
scan_size |
None |
tuple or None |
Tuple describing the number of scan points in y- and x- directions. Required for constraining positions and tilts. |
num_slices |
1 |
int |
Number of slices in the object. |
Refinable Arrays¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
obj |
np.ones((1, 1, num_slices, 1)) |
numpy.ndarray |
Initial guess for the transmission function to be retrieved. Shape: (y, x, z, modes). If the y and x dimensions are insufficient for the scan grid, the object will be padded with ones. |
probe |
None |
numpy.ndarray or None |
Real-space probe. Shape: (y, x, modes). For advanced experiments, the probe can be 4D (y, x, modes, subscans). If None, PyPty will automatically initialize the beam from the dataset. |
positions |
np.array([[0.0, 0.0]]) |
numpy.ndarray |
Scan positions in pixels of the reconstruction. Shape: [N_measurements, 2], formatted as [[y0, x0], [y1, x1], ..., [yn, xn]]. Single-shot experiments can define one common scan point, e.g., [[0,0]]. |
tilts |
np.array([[0.0, 0.0, 0.0, 0.0, 0.0, 0.0]]) |
numpy.ndarray |
Tilt angles in real and reciprocal spaces. There are 3 types of tilts in PyPty framework: before, inside and after. First one is a beam tilt before the specimen, i.e. a shift in aperture plane. Second type is a tilt inside of a specimen, i.e. after each slice the beam is shifted in real space. Third type is a post-specimen tilt i.e. a shift in a detector plane. All three types of shifts are contained in this tilt array. Shape: [N_measurements, 6]. Format: [[y0_before, x0_before, y0_inside, x0_inside, y0_after, x0_after], ..., [yN, xN]]. Single-shot experiments can define one common tilt (with shape [1, 6]). |
tilt_mode |
0 |
int |
Mode for applying tilts: 0, 3, 4 for inside, 2, 4 for before, and 1, 3, 4 for after the specimen. |
static_background |
0 |
numpy.ndarray or float |
Static background intensity. Shape should match initial patterns but padded by data_pad//upsample_pattern. Use 0 for no static offset. If provided as postive float, the algorithm will initialize the backgrund with a proper shape on its own. |
beam_current |
None |
numpy.ndarray or None |
Accounts for different currents (or exposure times) during measurements. If provided, must be a 1D array with length matching N_measurements. |
Propagation, Shifting, and Resizing¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
propmethod |
"multislice" |
str |
Wave propagation method. Options: "multislice", "better_multislice", and "yoshida". The last two are higher precision but slower. |
allow_subPixel_shift |
True |
bool |
Allow subpixel shifts. If False, positions will be rounded to integers until refined. |
dynamically_resize_yx_object |
False |
bool or int or pypty_lambda |
If position updates become too large, the object will be padded to accommodate the new scan grid. If set to a positive integer, resizing occurs when position updates exceed this value. |
extra_space_on_side_px |
0 |
int |
Extra space added around the object in pixels. |
Bandwidth Limitation¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
damping_cutoff_multislice |
2/3 |
float |
Frequency cutoff for multislice beam propagation. Values larger than 2/3 can cause aliasing artifacts. Recommended ≤ 2/3. |
smooth_rolloff |
0 |
float |
Rolloff parameter for smooth frequency cutoffs. |
update_extra_cut |
0.005 |
float |
Extra frequency cutoff for the full object. Ensures bandwidth limitation beyond the cropped ROIs of the multislice object. |
lazy_clean |
False |
bool |
If True, the full transmission function will not be bandwidth-limited (only cropped ROIs will be). Recommended: False. |
Optimization Settings¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
algorithm |
"lsq_sqrt" |
str |
Error metric for reconstruction comparison. Options: "lsq_sqrt" (Gaussian), "ml" (Poisson), "lsq" (classic summed squared error), and "lsq_sqrt_2" (modified Gaussian). If data is compressed via virtual detectors, the only option is "lsq_compressed" (summed squared error between signals). |
epoch_max |
200 |
int |
Maximum number of epochs (iterations). |
wolfe_c1_constant |
0.1 |
float or pypty_lambda |
Wolfe condition parameter (C1). Prevents update steps from being too large. Must be > 0 and < C2. Larger values enforce shorter step size. |
wolfe_c2_constant |
0.9 |
float or pypty_lambda |
Wolfe condition parameter (C2). Prevents update steps from being too small. Must be > C1 but < 1. Larger values allow larger steps. |
loss_weight |
1 |
float or pypty_lambda |
Weight applied to the loss function. |
max_count |
20 |
int or None |
Maximum number of forward-backward propagations per line search iteration. If exceeded, the update is rejected and history is reset. Use None or np.inf to disable. |
reduce_factor |
0.1 |
float |
Factor for reducing step size when the first Wolfe condition is not met. |
optimism |
3.0 |
float |
Factor for increasing step size when the second Wolfe condition is not met. To prevenet algorithm from going back and forth during linesearch, multiplication of optimism and reduce_factor (or of any powers of them) should not be equal to 1. |
min_step |
1e-20 |
float |
Minimum step size. If the step falls below this value, the algorithm resets history. Use 0 to disable. |
hist_length |
10 |
int or np.inf or pypty_lambda |
BFGS optimization history length. Values: 0 (Gradient Descent), 1 (Conjugate Gradient), N>1 (Limited-memory BFGS), np.inf (Full BFGS). |
update_step_bfgs |
1 |
float or pypty_lambda |
Common step applied to all refinable quantities. By default, after the first iteration, a Barzilai-Borwein method is used to inistialize the inverse Hessian, so most of the time, an update step of 1 should be accepted. Only during the very first iteration the linesearch might take some time to find an appropriate step. |
phase_only_obj |
False |
bool or pypty_lambda |
Whether to consider the object as phase-only. |
tune_only_probe_phase |
False |
bool or pypty_lambda |
Optimize only the reciprocal-space phase (CTF) of the probe. |
tune_only_probe_abs |
False |
bool or pypty_lambda |
Optimize only the reciprocal-space amplitude (aperture) of the probe. |
reset_history_flag |
False |
bool or pypty_lambda |
Flag to reset optimization history. See section "lambda-types" in this document. If provided, history will be manually resetted. |
Updating Refinable Arrays¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
update_probe |
1 |
bool or pypty_lambda |
Whether to update the probe (1 for yes, 0 for no). |
update_obj |
1 |
bool or pypty_lambda |
Whether to update the object (1 for yes, 0 for no). |
update_probe_pos |
0 |
bool or pypty_lambda |
Whether to update probe positions (1 for yes, 0 for no). |
update_tilts |
0 |
bool or pypty_lambda |
Whether to update tilt angles (1 for yes, 0 for no). |
update_beam_current |
0 |
bool or pypty_lambda |
Whether to update beam current (1 for yes, 0 for no). |
update_aberrations_array |
0 |
bool or pypty_lambda |
Whether to update aberration array (1 for yes, 0 for no). |
update_static_background |
0 |
bool or pypty_lambda |
Whether to update static background (1 for yes, 0 for no). |
Multiple Illumination Functions¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
aberrations_array |
np.array([[0.0]]) |
numpy.ndarray |
Array of aberration values for multiple beams. Useful for large fields of view where the beam changes. Shape: [N_subscans, N_aberrations]. |
phase_plate_in_h5 |
None |
str or None |
Path to an HDF5 file containing phase plates for different measurements. Dataset name should be "configs". Shape: [N_measurements, Y_probe, X_probe]. |
aberration_marker |
None |
numpy.ndarray or None |
Marker for multiple CTFs. Should be a 1D array of length N_measurements, where each entry corresponds to a CTF index in aberrations_array. |
probe_marker |
None |
numpy.ndarray or None |
Marker for probe variations. If provided, the probe should have shape [y, x, modes, N_subscans], and this array should contain indices specifying which probe to use for each measurement. |
Memory Usage¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
load_one_by_one |
True |
bool |
If True, data is loaded dynamically to save GPU memory. If False, all data is loaded at once (faster but memory-intensive). |
smart_memory |
True |
bool or pypty_lambda |
If True, memory is managed intelligently, clearing cache when necessary to prevent memory fragmentation. |
remove_fft_cache |
False |
bool |
If True, FFT cache is removed periodically to save memory. (Experimental feature) |
compute_batch |
"auto" |
int or str |
Batch size for multislice computation. Default value "auto" will automatically estimate a value that would fit into your memory, but ideally one should balance it by hand for a particular GPU. Increasing this can speed up reconstruction but requires more GPU memory. Super large values are also useless as at some point you will reash the limit the compute capability. |
force_dataset_dtype |
default_float_cpu |
numpy.dtype |
Forces the dataset to be stored in a specified data type. Can help reduce memory usage at the cost of precision. |
preload_to_cpu |
False |
bool |
If True, preloads data to CPU before transferring it to GPU, improving transfer speeds for .h5 datasets. |
force_pad |
False |
bool |
If True, pads data at the start of reconstruction (uses more memory but speeds up computation). If False, padding is applied on the fly to save memory. |
memory_saturation |
0.7 |
float |
If compute batch is set to "auto", this ratio will be used to estimate a compute batch that would requiere memory_saturation of the avalible GPU memory. If compute_batch is integer, memory_saturation is ignored. |
Constraints Contributing to the Loss¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
mixed_variance_weight |
0 |
float or pypty_lambda |
Regularization weight that prevents low-frequency variations between object states. |
mixed_variance_sigma |
0.5 |
float or pypty_lambda |
Controls the spatial frequency range affected by mixed_variance_weight. |
probe_constraint_mask |
None |
numpy.ndarray or None |
Mask for probe constraint in reciprocal space. Masked pixels are regularized using L2 norm. |
probe_reg_constraint_weight |
0 |
float |
L2 regularization weight for the probe in reciprocal space. |
window_weight |
0 |
float or pypty_lambda |
L2 regularization weight for the probe in real space. |
window |
None |
numpy.ndarray or None or or pypty_lambda |
Window function used to constrain the probe in real space. Masked pixels are damped using L2 regularization. It can be either a 2d- real valued array with the same shape as upsampled and padded beam or a list containing two values: inner radius (fraction) and outer radius (fraction). Fractions will be multiplied with half of the probe width, everything inside of window will be kept intact, everything outside will be zeroed and intermediate values will be slighly damped. |
abs_norm_weight |
0 |
float |
L1 regularization weight applied to the absorptive potential (negative log of the transmission function’s absolute value). |
phase_norm_weight |
0 |
float or pypty_lambda |
L1 regularization weight applied to the phase of the object. |
atv_weight |
0 |
float or pypty_lambda |
Weight for Adaptive Total Variation (ATV) regularization on the transmission function. |
atv_q |
1 |
float or pypty_lambda |
ATV q parameter (controls the strength of smoothing). Recommended: 1. |
atv_p |
2 |
float or pypty_lambda |
ATV p parameter (1 = L1-like regularization, 2 = L2-like smoothing). Recommended: 2. |
fast_axis_reg_weight_positions |
0 |
float or pypty_lambda |
Regularization weight for fast-axis scan positions. Reduces the acceleration along one line. |
slow_axis_reg_weight_positions |
0 |
float or pypty_lambda |
Regularization weight for slow-axis scan positions. Reduces the acceleration along one column. |
fast_axis_reg_weight_tilts |
0 |
float or pypty_lambda |
Regularization weight for fast-axis tilts. Reduces the acceleration along one line. |
slow_axis_reg_weight_tilts |
0 |
float or pypty_lambda |
Regularization weight for slow-axis tilts. Reduces the acceleration along one column. |
deformation_reg_weight_positions |
0 |
float or pypty_lambda |
Regularization weight for enfourcing a regular (but deformed) scan grid. |
deformation_reg_weight_tilts |
0 |
float or pypty_lambda |
Regularization weight for enfourcing a regular (but deformed) tilts grid. |
Constraints That Modify the Object and Probe 'By Hand'¶
Warning: These constraints reset the BFGS history when applied.
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
apply_gaussian_filter |
False |
bool or pypty_lambda |
Applies a Gaussian filter to the phase of the object. |
apply_gaussian_filter_amplitude |
False |
bool or pypty_lambda |
Applies a Gaussian filter to the amplitude of the object. |
beta_wedge |
0 |
float or pypty_lambda |
Removes high kz frequencies for low kx and ky in 3D object FFTs. |
keep_probe_states_orthogonal |
False |
bool or pypty_lambda |
Enforces orthogonality of probe modes. |
do_charge_flip |
False |
bool |
Performs charge flipping on the object. |
cf_delta_phase |
0.1 |
float |
Delta phase for charge flipping. |
cf_delta_abs |
0.01 |
float |
Delta amplitude for charge flipping. |
do_charge_flip |
False |
bool or pypty_lambda |
Perform charge flipping on the object. |
cf_delta_phase |
0.1 |
float or pypty_lambda |
Delta phase for charge flipping. |
cf_delta_abs |
0.01 |
float or pypty_lambda |
Delta amplitude for charge flipping. |
cf_beta_phase |
-0.95 |
float or pypty_lambda |
Beta phase parameter for charge flipping. |
cf_beta_abs |
-0.95 |
float or pypty_lambda |
Beta amplitude parameter for charge flipping. |
fancy_sigma |
None |
None or float oor pypty_lambda |
Custom sigma parameter to enforce atomicity. |
restart_from_vacuum |
False |
bool or pypty_lambda |
Resets the object to 1 while keeping other parameters unchanged. See section "lambda-types" in this document. |
reset_positions |
False |
bool or pypty_lambda |
Resets the positions to initial guess while keeping other parameters unchanged. See section "lambda-types" in this document. |
Beam Initialization¶
| Parameter | Default Value | Default Data Type | Description |
|---|---|---|---|
n_hermite_probe_modes |
None |
tuple or None |
Number of Hermite probe modes. A tuple [nx, ny] specifying mode orders in x and y directions. If None, no Hermite modes are applied. |
defocus_spread_modes |
None |
numpy.ndarray or None |
1D array with different defocus values for initializing probe modes. Useful for simulating defocus spread in the beam. |
aberrations |
None |
numpy.ndarray or None |
1D array of aberration coefficients in Krivanek notation, e.g., C10, C12a, C12b, C21a, C21b, C23a, C23b, C30. Units: Angstroms. |
extra_probe_defocus |
0 |
float |
Extra probe defocus applied in Angstroms. Useful for adjusting initial beam focus in multislice reconstructions. |
estimate_aperture_based_on_binary |
0 |
float |
If > 0, the aperture is estimated based on a binary threshold. Pixels in the data larger than mean(data) * estimate_aperture_based_on_binary are considered part of the aperture. |
beam_ctf |
None |
numpy.ndarray or None |
Beam Contrast Transfer Function (CTF). If provided, must be a 2D NumPy array with dimensions matching the upsampled probe size. |
mean_pattern |
None |
numpy.ndarray or None |
Mean diffraction pattern used for probe initialization. If provided, the probe is created using an inverse Fourier transform of this pattern. |
Notebook / example pipeline¶
import numpy as np
import matplotlib.pyplot as plt
import sys
import pypty
from matplotlib.patches import Rectangle
from matplotlib.patches import Circle
from matplotlib.colors import LogNorm
from matplotlib.patches import Ellipse
from matplotlib import rcParams
plt.style.use('dark_background')
print(pypty.__version__)
2.1
Specify raw data and output path¶
path="/home/anton/data/test_folder/"
name="mops"
path_h5=path+ name+".h5"
path_json=""
path_raw=path+name+".npy"
output_folder="/home/anton/data/test_folder/test_mops_2/"
Create h5 data¶
pypty.initialize.create_pypty_data(path_raw, path_h5, swap_axes=False,
flip_ky=0,flip_kx=0, comcalc_len=200*200,
comx=0, comy=0, bin=1, crop_left=None,
crop_right=None, crop_top=None, crop_bottom=None, normalize=False, exist_ok=1)
****************************************************************************** ************************ Creating an .h5 File ******************************** ****************************************************************************** .h5 File exists!
Parameters¶
experimental_params={
'output_folder': output_folder,
'path_json': path_json,
'data_path': path_h5,
'conv_semiangle_mrad': 4,
'scan_size': [28,28],
'scan_step_A': 20,
'fov_nm': 2*27,
'acc_voltage': 200, ## kV
'PLRotation_deg': 0, # deg
'bright_threshold': 0.2,
'plot': True,
'print_flag': 1,
'data_pad': None,
'sample_name': 'nano_mops'
}
pypty_params={
'update_obj': 1,
'update_probe': 1,
'hist_length': 10,
'optimizer': "bfgs",
'update_step_bfgs': lambda x: 1e-2 if x==0 else 1,
'n_parallel_meas': 1,
'min_step': 1e-30,
'optimism': 3,
'reduce_factor': 1/10,
'wolfe_c1_constant': 1e-1,
'dynamically_resize_yx_object': 5,
'aberrations': [-2e4,0,0], ## Angstrom # 200A
'wolfe_c2_constant': 0.9,
'update_extra_cut': 0.02,
'save_inter_checkpoints': True,
'save_checkpoints_every_epoch': False,
'algorithm': 'lsq_sqrt',
'use_full_FOV': True,
'epoch_max': 100,
'load_one_by_one': False,
'preload_to_cpu': False,
'smart_memory': False,
'force_pad': True,
'default_dtype': 'double',
'damping_cutoff_multislice': 0.66,
}
pypty_params=pypty.initialize.append_exp_params(experimental_params, pypty_params)
****************************************************************************** ******** Attaching the experimental parameters to your PyPty preset. ********* ****************************************************************************** json is not provided!
Radius of bright field is 62.52 px pixel size in A: 1.531e+00 Pixel size after padding: 1.02e+00 Å
tcBF¶
pypty_params=pypty.tcbf.run_tcbf_alignment(pypty_params,
aberrations=[-1.5e4,0,0],
binning_for_fit=np.tile([7],30),
refine_box_dim=10, upsample=3,
reference_type="bf", optimize_angle=False,
cancel_large_shifts=0.9,
subscan_region=None, interpolate_scan_factor=1,
cross_corr_type="phase"
)
****************************************************************************** ************************ Running the tcBF alignment ************************** ****************************************************************************** Initial aberrations: C10 -1.50e+04 Å, C12a 0.00e+00 Å, C12b 0.00e+00 Åshape of data: (784, 256, 256) scan size: [28 28] Initializing the abberation fit! ---> Starting iteration 1/30 of the CTF fit, this binning is 7 Binning the data by 7 FFT of binned data is done!
/home/anton/pypty/pypty/tcbf.py:304: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. cp.fft.config.clear_plan_cache() ## free the memory
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.09e+04 A, C12a 2.92e+02 A, C12b 6.52e+02 A ---> Starting iteration 2/30 of the CTF fit, this binning is 7 Using results of previous binning
/home/anton/pypty/pypty/tcbf.py:588: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. cp.fft.config.clear_plan_cache()
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 2.79e+00 A, C12b 1.21e+00 A ---> Starting iteration 3/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 4/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 5/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 6/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 7/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 8/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 9/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 10/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 11/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 12/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 13/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 14/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 15/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 16/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 17/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 18/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 19/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 20/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 21/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 22/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 23/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 24/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 25/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 26/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 27/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 28/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 29/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A ---> Starting iteration 30/30 of the CTF fit, this binning is 7 Using results of previous binning
Found matching shifts for 258/287 pixels. CTF fitted successfully: True.
Fitted aberrations: C10 -2.23e+04 A, C12a 7.74e-01 A, C12b -1.89e+00 A Final CTF Fit done!
/home/anton/pypty/pypty/tcbf.py:625: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. cp.fft.config.clear_plan_cache()
im, pix=pypty.tcbf.upsampled_tcbf(pypty_params,
round_shifts=True,
upsample=5)
plt.imshow(im, cmap="gray")
plt.title("Upsampled tcBF")
plt.colorbar()
plt.show()
****************************************************************************** ************************ Creating upsampled tcBF Image *********************** ****************************************************************************** 6.40e-05 rad per pixel your final pixel size will be 4.00 Å final shape of image will be: (240, 240)
100%|██████████| 12281/12281 [00:02<00:00, 4569.58it/s] /home/anton/pypty/pypty/tcbf.py:856: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. xp.fft.config.clear_plan_cache()
Direct Ptychography¶
o=pypty.direct.wdd(pypty_params)
plt.imshow(np.angle(o), cmap="gray")
plt.title("WDD Phase")
plt.colorbar()
plt.axis("off")
plt.show()
/home/anton/pypty/pypty/direct.py:46: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. cp.fft.config.clear_plan_cache()
Provided aberrations: C10: -2.23e+04 Å; C12a: 7.74e-01 Å; C12b: -1.89e+00 Å;
/home/anton/pypty/pypty/direct.py:170: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. cp.fft.config.clear_plan_cache() 100%|██████████| 256/256 [00:06<00:00, 39.32it/s] /home/anton/pypty/pypty/direct.py:182: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. cp.fft.config.clear_plan_cache()
-->1st FFT done
100%|██████████| 28/28 [00:00<00:00, 51.31it/s] /home/anton/pypty/pypty/direct.py:201: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. cp.fft.config.clear_plan_cache()
-->2nd FFT done (array(14), array(14))
Iterative Ptychography¶
pypty.iterative.run(pypty_params)
***************************************************** ************************* ************************ Starting PyPty Reconstruction *********************** ****************************************************************************** Path to the dataset: /home/anton/data/test_folder/mops.h5 Saving the results in /home/anton/data/test_folder/test_mops_2/ Saving the parameters in /home/anton/data/test_folder/test_mops_2/params.pkl The log file will be saved as /home/anton/data/test_folder/test_mops_2/loss.csv ****************************************************************************** ****************************************************************************** ****************************************************************************** The probe was generated based on the mean pattern! WARNING! Range of specified scan positions was larger than the shape of the object, adding ones to the right and/or bottom. New shape of the object is 913 px in y, 913 px in x, 1 slice(-s) , 1 mode(-s) !!!!! Provided aberrations: C10: -2.23e+04 Å; C12a: 7.74e-01 Å; C12b: -1.89e+00 Å; ---------> Time: 0: 0:17. Epoch 99. Using lsq_sqrt error metric with bfgs-10 optimzer. Loss: 5.07e+01. SSE: 7.34e+01. Updating object, probe; Done :)
/home/anton/pypty/pypty/iterative.py:336: FutureWarning: cupy.fft.cache.clear_plan_cache is experimental. The interface can change in the future. cp.fft.config.clear_plan_cache()
Visualisation¶
output_folder="/home/anton/data/test_folder/test_mops_2/"
o,p,g=np.load(output_folder+"co.npy"), np.load(output_folder+"cp.npy"), np.load(output_folder+"cg.npy")
phase=np.angle(o[:,:,0,0])
plt.imshow(phase, cmap="gray")
plt.colorbar()
plt.axis("off")
plt.show()
pypty.vaa.plot_modes(p)
figs=pypty.vaa.outputlog_plots(output_folder+"loss.csv", 10, True)
API Reference
pypty.initialize¶
create_pypty_data
¶
Create a PyPty-style .h5 dataset from 4D-STEM data.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
Path to
TYPE:
|
path_output
|
Output file path for the PyPty
TYPE:
|
swap_axes
|
Swap the last two axes (kx, ky). Default is False.
TYPE:
|
flip_ky
|
Flip the data along specific axes. Default is False.
TYPE:
|
flip_kx
|
Flip the data along specific axes. Default is False.
TYPE:
|
flip_y
|
Flip the data along specific axes. Default is False.
TYPE:
|
flip_x
|
Flip the data along specific axes. Default is False.
TYPE:
|
comcalc_len
|
Number of patterns to use to estimate center-of-mass. Default is 1000.
TYPE:
|
comx
|
Predefined center-of-mass. If None, it will be computed.
TYPE:
|
comy
|
Predefined center-of-mass. If None, it will be computed.
TYPE:
|
bin
|
Spatial binning factor on the diffraction patterns. Default is 1.
TYPE:
|
crop_left
|
Crop edges of patterns. Defaults are None.
TYPE:
|
crop_right
|
Crop edges of patterns. Defaults are None.
TYPE:
|
crop_top
|
Crop edges of patterns. Defaults are None.
TYPE:
|
crop_bottom
|
Crop edges of patterns. Defaults are None.
TYPE:
|
normalize
|
Normalize pattern sums to 1. Default is False.
TYPE:
|
cutoff_ratio
|
Mask out pixels farther than
TYPE:
|
pad_k
|
Padding to apply to diffraction patterns. Default is 0.
TYPE:
|
data_dtype
|
Output data type. Default is np.float32.
TYPE:
|
rescale
|
Scale factor for intensity. Default is 1.
TYPE:
|
exist_ok
|
If True, skip writing if file exists. Default is True.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
Notes
Saves a .h5 file containing processed 4D-STEM data with standardized formatting for PyPty.
append_exp_params
¶
Attach experimental parameters to a PyPty preset dictionary and callibrate an extisting PyPty preset to new data.
| PARAMETER | DESCRIPTION |
|---|---|
experimental_params
|
Dictionary containing experimental metadata and setup for PyPty reconstruction.
TYPE:
|
pypty_params
|
Existing PyPty preset to update, a filepath to a preset, or None to create a new one.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated PyPty parameter dictionary. |
Notes
experimental_params should contain following entries:
data_path - path to a PyPty-style 3d .h5 file [N_measurements, ky,kx] or .npy Nion-style 4d-stem dataset (or 3d .npy dataset)
masks - 3d numpy array or None. if data is compressed provide the virtual detectors (masks) shape should be [N_masks,ky,kx]
output_folder - path to an outputfolder where the results will be stored
path_json - path to a nion-style json file with metadata (optional)
acc_voltage - float, accelerating voltage in kV
One or multiple of the following callibrations:
rez_pixel_size_A - reciprocal pixel size in Å^-1
rez_pixel_size_mrad - reciprocal pixel size in mrad
conv_semiangle_mrad - beam convergence semi-angle in mrad
aperture - (optional)- binary 2D mask
bright_threshold - threshold to estimate an aperture, everything above threshold times maximum value in a pacbed will be concidered as bright field disk.
data_pad - int, reciprocal space padding. If None (default), pading is 1/4 of the total width of a diffraction pattern
upsample_pattern - int, default 1 (no upsampling)
aberrations - list or 1d numpy array containing beam aberrations (in Å). Aberrations are stored in Krivanek notation, e.g. C10, C12a, C12b, C21a, C21b, C23a, C23b, C30 etc
defocus - float, default 0. Extra probe defocus besides the one contained in aberrations.
scan_size - tuple of two ints, number of scan points along slow (y) and fast (x) axes. Optional. If no scan step or position grid is provided, it will be used to get the scan step
scan_step_A - float, scan step (STEM pixel size) in Å.
fov_nm - float, FOV along the fast axis in nm.
special_postions_A - 2d numpy array, default None. If you acquiered a data on a special non-rectangular grid, please specify the positions in Å via this array for all measurements in a following form: [y_0,x_0],[y_1,x_1],....[y_n,x_n]]
transform_axis_matrix- 2x2 matrix for postions transformation
PLRotation_deg - float, rotation angle between scan and detector axes. Default None. If None, a DPC measurement will be exectuted to get this angle. !!!!!!! Note that negative PLRotation_deg values rotate scan counter clockwise and diffraction space clockwise !!!!!!!!!!!
flip_ky - boolean Flag. Default is False. If no PyPty-style h5 data was created, this flag will flip the y-axis of diffraction patterns.
total_thickness - total thickness of a sample in Å. Has no effect if num_slices is 1 and propagation method (pypty_params entry) is multislice
num_slices - integer, number of slices, default is 1.
plot - boolean Flag, default is True
print_flag - integer. Default is 1. If 0 nothing will be printed. 1 prints only thelatest state of the computation, 2 prints every state as a separate line. 3 prints the linesearch progress in iterative optimization. 4 prints everything that 3 does and if constraints are applied, it prints how they contribute so that a user can configure the weights properly.
save_preprocessing_files - Boolean Flag. Default is True.
get_offset
¶
Compute pixel offsets between scan grid and reconstruction grid. In PyPty framework, scan grid is usually rotated to compensate the misalignment between scan- and detector- axes. Also, a reconstruction grid is larger than the scanned FOV, this is done to accomodate the extent of the probe.
| PARAMETER | DESCRIPTION |
|---|---|
x_range
|
Scan dimensions.
TYPE:
|
y_range
|
Scan dimensions.
TYPE:
|
scan_step_A
|
STEM scan step size in Å.
TYPE:
|
detector_pixel_size_rezA
|
Reciprocal space pixel size in Å⁻¹.
TYPE:
|
patternshape
|
Shape of diffraction patterns.
TYPE:
|
rot_angle_deg
|
Rotation between scan and detector axes (degrees).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
offy, offx : float
|
Offset values (in reconstruction pixels). |
get_positions_pixel_size
¶
Generate scan positions in reconstruction pixel units.
| PARAMETER | DESCRIPTION |
|---|---|
x_range
|
Scan grid size.
TYPE:
|
y_range
|
Scan grid size.
TYPE:
|
scan_step_A
|
STEM scan step size (Å).
TYPE:
|
detector_pixel_size_rezA
|
Pixel size in reciprocal space (Å⁻¹).
TYPE:
|
patternshape
|
Shape of the diffraction pattern.
TYPE:
|
rot_angle_deg
|
Scan-detector rotation angle in degrees. Default is 0.
TYPE:
|
flip_x
|
Flip scan axes. Default is False.
TYPE:
|
flip_y
|
Flip scan axes. Default is False.
TYPE:
|
print_flag
|
Print pixel size. Default is False.
TYPE:
|
transform_axis_matrix
|
Optional 2x2 matrix to apply to positions.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
positions
|
Scan positions in reconstruction pixels.
TYPE:
|
pixel_size
|
Size of one reconstruction pixel in Å.
TYPE:
|
get_grid_for_upsampled_image
¶
Map coordinates of an upsampled image onto the reconstruction grid.
This function calculates where pixel of an arbitary image (e.g. upsampled tcBF image) will land on a grid corresponding to a ptychographic reconstruction.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
Dictionary of PyPty reconstruction parameters.
TYPE:
|
image
|
2D image (e.g., upsampled tcBF) to map.
TYPE:
|
image_pixel_size
|
Pixel size of the image in Å.
TYPE:
|
left_zero_of_scan_grid
|
Pixel offset on left side of image relative to scan grid. Default is 0.
TYPE:
|
top_zero_of_scan_grid
|
Pixel offset on top side of image relative to scan grid. Default is 0.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
sc
|
Array of pixel coordinates [[y, x], ...] in reconstruction grid units.
TYPE:
|
get_ptycho_obj_from_scan
¶
Construct an initial object guess using interpolated phase and amplitude maps. You can use output of dpc, wdd of tcBF reconstructions to generate it.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
PyPty parameter dictionary.
TYPE:
|
num_slices
|
Number of slices or "auto" to estimate from max phase shift.
TYPE:
|
array_phase
|
2D phase map to interpolate.
TYPE:
|
array_abs
|
2D amplitude map to interpolate.
TYPE:
|
scale_phase
|
Scale factor for phase.
TYPE:
|
scale_abs
|
Scale factor for amplitude.
TYPE:
|
scan_array_A
|
Spatial reference grid for the input maps (in Å).
TYPE:
|
fill_value_type
|
Padding strategy outside scanned region: None, "edge", or "median".
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated PyPty parameter dictionary with object guess. |
create_aberrations_chunks
¶
Create chunks, i.e. multiple subscans with independent beam aberrations. Usefull for large fields of view where the beam is varyying. If applied, the iterative reconstruction will have the same beam in each subscan, but apply a different CTF in each of these regions.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
chop_size
|
Size of each subscan region (in scan points).
TYPE:
|
n_abs
|
Number of aberration coefficients per region.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated parameter dictionary with aberration array and marker. |
create_probe_marker_chunks
¶
Creates chunks, i.e. multiple subscans with independent beam aberrations. Usefull for large fields of view where the beam is varyying. If applied, the iterative reconstruction will have the a differenet beam in each of these subscans.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
chop_size
|
Size of each subscan region (in scan points).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary with probe marker. |
create_sub_sequence
¶
Define a measurement subsequence for local reconstructions.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
left
|
Leftmost scan coordinate.
TYPE:
|
top
|
Top scan coordinate.
TYPE:
|
width
|
Width of subregion (in scan points).
TYPE:
|
height
|
Height of subregion (in scan points).
TYPE:
|
sub
|
Sampling factor (take every Nth point).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated parameter dictionary with |
create_sequence_from_points
¶
Create scan subsequence around specified feature points.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
yf
|
Y-coordinates of feature points (in scan points).
TYPE:
|
xf
|
X-coordinates of feature points.
TYPE:
|
width_roi
|
Width of the reconstruction window around each point.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
List of scan indices to reconstruct. |
rotate_scan_grid
¶
Apply a rigid rotation to the scan grid.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
angle_deg
|
Rotation angle in degrees.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary with rotated positions and angle. |
conjugate_beam
¶
Apply beam conjugation (flip defocus and aberrations).
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary with conjugated probe and CTF. |
get_focussed_probe_from_vacscan
¶
Reconstruct a focused probe from a vacuum PACBED pattern.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
mean_pattern
|
Measured PACBED from vacuum.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary with a probe estimate. |
append_aperture_to_params
¶
Append a measured aperture to the reconstruction parameters.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
mean_pattern
|
Aperture image to be rescaled and added.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary with aperture. |
tiltbeamtodata
¶
Align the probe momentum to the center of the measured PACBED pattern.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
align_type
|
Type of alignment ("com" or "cross_corr").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary with shifted probe. |
get_approx_beam_tilt
¶
Estimate scan-position-dependent beam tilt from PACBED.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
power
|
Degree of polynomial fitting.
TYPE:
|
make_binary
|
If True or float > 0, binarize patterns.
TYPE:
|
percentile_filter_value
|
Value for optional percentile filtering.
TYPE:
|
percentile_filter_size
|
Filter size if filtering is enabled.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary with estimated tilts. |
pypty.dpc¶
get_curl
¶
Compute the standard deviation of the curl of a rotated DPC vector field. This is the objective function for minimization. This particular function was copied from a DPC plugin written by Jordan Hachtel.
| PARAMETER | DESCRIPTION |
|---|---|
angle
|
Rotation angle in radians.
TYPE:
|
dpcx
|
X-component of the DPC signal.
TYPE:
|
dpcy
|
Y-component of the DPC signal.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Standard deviation of the curl after rotation. |
get_curl_derivative
¶
Compute the derivative of the curl-based objective function with respect to rotation angle.
| PARAMETER | DESCRIPTION |
|---|---|
angle
|
Rotation angle in radians.
TYPE:
|
dpcx
|
X-component of the DPC signal.
TYPE:
|
dpcy
|
Y-component of the DPC signal.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Derivative of the curl-based objective function. |
GetPLRotation
¶
Estimate rotation angle that minimizes the curl of the DPC signal.
| PARAMETER | DESCRIPTION |
|---|---|
dpcx
|
X-component of the DPC signal (2D array).
TYPE:
|
dpcy
|
Y-component of the DPC signal (2D array).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Optimal rotation angle in radians. |
fft_based_dpc
¶
FFT-based DPC phase reconstruction. If you setted up the pypty_params properly, you would only need to specify the hpass and lpass values, both are non-negative floats.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary with dataset and calibration settings.
TYPE:
|
hpass
|
High-pass filtering coefficient (default is 0).
TYPE:
|
lpass
|
Low-pass filtering coefficient (default is 0).
TYPE:
|
save
|
Whether to save the reconstructed phase (default is False).
TYPE:
|
comx
|
Precomputed center-of-mass x-component.
TYPE:
|
comy
|
Precomputed center-of-mass y-component.
TYPE:
|
plot
|
If True, display the phase reconstruction.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
pot
|
Reconstructed 2D phase image.
TYPE:
|
pypty_params
|
Updated parameter dictionary with computed COM and rotation angle.
TYPE:
|
iterative_dpc
¶
Iterative DPC phase reconstruction. If you setted up the pypty_params properly, you would only need to specify the hpass and lpass values, both are non-negative floats.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
PyPty parameter dictionary.
TYPE:
|
num_iterations
|
Number of gradient descent iterations (default is 100).
TYPE:
|
beta
|
Step reduction factor for backtracking (default is 0.5).
TYPE:
|
hpass
|
High-pass filtering coefficient (default is 0).
TYPE:
|
lpass
|
Low-pass filtering coefficient (default is 0).
TYPE:
|
step_size
|
Initial gradient descent step size (default is 0.1).
TYPE:
|
COMx
|
X-component of COM map.
TYPE:
|
COMy
|
Y-component of COM map.
TYPE:
|
px_size
|
Scan step size in Ångströms.
TYPE:
|
print_flag
|
Whether to print progress information (default is False).
TYPE:
|
save
|
Whether to save the result to disk (default is False).
TYPE:
|
select
|
Optional binary mask to constrain reconstruction.
TYPE:
|
plot
|
If True, plot the reconstruction result.
TYPE:
|
use_backtracking
|
Whether to use backtracking line search (default is True).
TYPE:
|
pad_width
|
Padding width to suppress FFT boundary artifacts (default is 5).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
padded_phase
|
Reconstructed 2D phase image.
TYPE:
|
iterative_poisson_solver
¶
Iterative solver for Poisson equation given a Laplacian map.
| PARAMETER | DESCRIPTION |
|---|---|
laplace
|
Input 2D array representing the Laplacian of the desired phase.
TYPE:
|
num_iterations
|
Number of iterations (default is 100).
TYPE:
|
beta
|
Step size reduction factor (default is 0.5).
TYPE:
|
hpass
|
High-pass filtering parameter (default is 0).
TYPE:
|
lpass
|
Low-pass filtering parameter (default is 0).
TYPE:
|
select
|
Optional binary mask to restrict updates.
TYPE:
|
px_size
|
Pixel size in Ångströms (default is 1).
TYPE:
|
print_flag
|
If True, print convergence status (default is False).
TYPE:
|
step_size
|
Initial gradient descent step size (default is 0.1).
TYPE:
|
use_backtracking
|
Whether to use backtracking line search (default is True).
TYPE:
|
pad_width
|
Number of pixels to pad around the solution (default is 1).
TYPE:
|
xp
|
Backend array library (NumPy or CuPy, default is NumPy).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Reconstructed 2D phase from the input Laplacian. |
pypty.tcbf¶
run_tcbf_alignment
¶
Align and fit the beam contrast transfer function (CTF) using 4D-STEM data.
This function estimates beam aberrations by aligning individual pixel images using cross-correlation and fitting a CTF model. It supports iterative fitting with various binning levels and options for low-frequency drift compensation.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Dictionary containing PyPTY experimental and reconstruction settings.
|
binning_for_fit
|
List (for integers) of binning factors for each iteration of the CTF fit.
TYPE:
|
save
|
Whether to save intermediate tcBF images and shift estimates.
TYPE:
|
optimize_angle
|
Whether to include probe rotation angle in the fit.
TYPE:
|
aberrations
|
Initial guess for aberrations. If None, n_aberrations_to_fit zeros will be used.
TYPE:
|
n_aberrations_to_fit
|
Number of aberrations to fit if no initial guess is provided.
TYPE:
|
reference_type
|
Reference used for cross-correlation ("bf" or "zero").
TYPE:
|
refine_box_dim
|
Radius (in pixels) of the interpolation box for sub-pixel shift refinement.
TYPE:
|
upsample
|
Factor for refining cross-correlation to estimate sub-pixel shifts.
TYPE:
|
cross_corr_type
|
Type of cross-correlation to use ("phase" or "classical").
TYPE:
|
cancel_large_shifts
|
Threshold (0–1) to ignore large shift outliers in the fit.
TYPE:
|
pattern_blur_width
|
Radius for optional circular blur mask applied to patterns.
TYPE:
|
scan_pad
|
Number of scan pixels to pad around the dataset (auto if None).
TYPE:
|
aperture
|
Aperture mask. If None, attempts to extract from parameters.
TYPE:
|
subscan_region
|
Subregion for CTF fitting: [left, top, right, bottom].
TYPE:
|
compensate_lowfreq_drift
|
Whether to compensate for pattern drift in large FOVs.
TYPE:
|
append_lowfreq_shifts_to_params
|
Whether to store low-frequency drift corrections in
TYPE:
|
interpolate_scan_factor
|
Factor to upsample the scan via interpolation (experimental).
TYPE:
|
binning_cross_corr
|
Binning factor before peak detection in cross-correlation.
TYPE:
|
phase_cross_corr_formula
|
Use analytical peak refinement formula for phase correlation.
TYPE:
|
f_scale_lsq
|
Scaling factor for residuals in
TYPE:
|
x_scale_lsq
|
Scaling for initial step size in
TYPE:
|
loss_lsq
|
Loss function for
TYPE:
|
tol_ctf
|
Tolerance (
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated parameter dictionary with fitted aberrations, defocus, and potentially updated scan positions and rotation. |
upsampled_tcbf
¶
Perform an upsampled tcBF (transmission coherent Bright Field) reconstruction.
This function reconstructs a tcBF image on an upsampled scan grid from 4D-STEM data.
It applies Fourier-based shifts to align the bright field pixel images and combines them into a final image.
Prior to calling this function, it is recommended to run the tcBF alignment routine to update pypty_params.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
Dictionary containing experimental parameters and reconstruction settings. This should include keys such as 'data_path', 'scan_size', 'aperture_mask', 'acc_voltage', etc.
TYPE:
|
upsample
|
Upsampling factor for the scan grid. Default is 5.
TYPE:
|
pad
|
Number of additional scan positions to pad on each side to avoid wrap-around artifacts. Default is 10.
TYPE:
|
compensate_lowfreq_drift
|
If True, compensates for low-frequency drift of the aperture. Requires that run_tcbf_alignment has been executed to provide drift corrections. Default is False.
TYPE:
|
default_float
|
Precision for floating point computations. Use 64 for higher precision or 32 for lower memory usage. Default is 64.
TYPE:
|
round_shifts
|
If True, shifts are rounded and alignment is performed using array roll operations. If False, FFT-based subpixel shifting is used. Default is False.
TYPE:
|
xp
|
Backend array module (e.g., numpy or cupy). Default is cupy.
TYPE:
|
save
|
Flag to save the output image. If True, the image is saved to disk.
Ignored if 'save_preprocessing_files' is set in
TYPE:
|
max_parallel_fft
|
Maximum number of FFTs to perform in parallel for vectorized processing. Default is 100.
TYPE:
|
bin_fac
|
Binning factor for the data in reciprocal space. Default is 1 (no binning).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Real-valued tcBF image reconstructed on the upsampled grid. |
|
Final pixel size in Ångströms after upsampling. |
run_tcbf_compressed_alignment
¶
Perform a CTF alignment using compressed 4D-STEM data and masked bright-field regions.
This function fits the beam CTF to the shifts between the individual pixel images of the 4d-stem dataset. It's the same as run_tcbf_alignment, but for compressed data. The shift estimation is done via cross-correaltion.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Dictionary containing experimental and reconstruction settings.
TYPE:
|
num_iterations
|
Number of fitting iterations to perform.
TYPE:
|
save
|
Whether to save intermediate tcBF images and shift maps. Default is True.
TYPE:
|
optimize_angle
|
Whether to include probe rotation angle in the CTF fit. Default is True.
TYPE:
|
aberrations
|
Initial guess for the aberration coefficients. If None, it will be inferred or zero-initialized.
TYPE:
|
n_aberrations_to_fit
|
Number of aberration coefficients to fit if
TYPE:
|
reference_type
|
"bf" to use the tcBF image as a reference, "zero" to use the central pixel. Default is "bf".
TYPE:
|
refine_box_dim
|
Size of the cropped region around the cross-correlation peak for sub-pixel refinement. Default is 10.
TYPE:
|
upsample
|
Upsampling factor for sub-pixel interpolation. Default is 3.
TYPE:
|
cross_corr_type
|
Cross-correlation method: "phase" (recommended) or "classic". Default is "phase".
TYPE:
|
cancel_large_shifts
|
Threshold to reject large shift outliers during fitting. Value between 0 and 1. Default is None.
TYPE:
|
pattern_blur_width
|
Width of blur kernel for patterns prior to analysis. Default is None.
TYPE:
|
scan_pad
|
Number of scan pixels to pad around the scan to prevent wrap-around. Default is auto.
TYPE:
|
aperture
|
Aperture mask defining pixels to analyze. If None, it will be loaded from
TYPE:
|
subscan_region
|
Optional subregion [left, top, right, bottom] on which to perform the alignment. Default is None.
TYPE:
|
compensate_lowfreq_drift
|
Whether to compute and correct for slow drifting of the aperture over time. Default is False.
TYPE:
|
append_lowfreq_shifts_to_params
|
If True, saves the low-frequency correction back into
TYPE:
|
interpolate_scan_factor
|
Experimental: interpolate scan grid by this factor (e.g., 2 for 2x upsampled grid). Default is 1.
TYPE:
|
binning_cross_corr
|
Binning factor applied to cross-correlation maps before refinement. Default is 1.
TYPE:
|
phase_cross_corr_formula
|
If True, uses analytical subpixel peak estimation for phase correlation. Default is False.
TYPE:
|
f_scale_lsq
|
Scaling factor for least squares residuals (
TYPE:
|
x_scale_lsq
|
Initial step scaling (
TYPE:
|
loss_lsq
|
Loss type for least squares optimizer. E.g., "linear", "huber". Default is "linear".
TYPE:
|
tol_ctf
|
Tolerance for optimizer convergence (
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary of reconstruction parameters including fitted aberrations and scan rotation. |
pypty.direct¶
wdd
¶
Perform Wigner Distribution Deconvolution (WDD).
This function applies Wigner Distribution Deconvolution to the provided data,
allowing for enhanced reconstruction of complex objects and probes. It handles both
GPU (via CuPy) and CPU (via NumPy) computations based on the availability of CuPy.
The pypty_params dictionary must be prepared via the initialize module.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
Dictionary containing calibrated parameters, including paths and settings for data processing.
TYPE:
|
eps_wiener
|
Epsilon parameter for the Wiener filter. Default is 1e-3.
TYPE:
|
thresh
|
If provided,
TYPE:
|
save
|
Whether to save output files (False by default). Ignored if
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
deconvolved_object
|
2D deconvolved complex object.
TYPE:
|
Notes
Make sure pypty_params includes all necessary paths and data arrays prior
to calling this function.
pypty.iterative¶
run
¶
Launch iterative reconstuction.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
Dictionary containing calibrated parameters, including paths and settings for data processing.
TYPE:
|
Notes
pypty_params dictionary can be constructed from a predefined preset and a given dataset via append_exp_params() function. Full list of expected entries can be found in the documentation,
bfgs_update
¶
This is one of the core functions of PyPty. It performs updates of all active reconstruction parameters (object, probe, positions, tilts, etc.) via l-BFGS algorithm.
| PARAMETER | DESCRIPTION |
|---|---|
Params
|
Way to many to describe right now
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
total_loss
|
Total loss value.
TYPE:
|
this_sse
|
Sum of squared errors.
TYPE:
|
constraint_contributions
|
List of reg. constraint values for this epoch
TYPE:
|
actual_step
|
Linesearch step that was found during this iteration
TYPE:
|
count
|
Number of linesearch iterations (calls of loss_and_direction) that was required during this epoch
TYPE:
|
d_value
|
Value of the direction derivative at this epoch
TYPE:
|
new_d_value
|
Value of the direction derivative at the newly estimated point
TYPE:
|
warnings
|
Warnings during this epoch
TYPE:
|
reset_bfgs_history
¶
Reset a global variable history_bfgs that contains information about previous steps.
pypty.objective¶
loss_and_direction
¶
Compute the total loss and gradients for ptychographic reconstruction.
This is the core function of PyPty that performs forward and backward propagation, calculates the loss between measured and simulated patterns, and computes the gradients of all active reconstruction parameters (object, probe, positions, tilts, etc.).
| PARAMETER | DESCRIPTION |
|---|---|
this_obj
|
Complex 4D object (current estimate)
TYPE:
|
full_probe
|
Complex probe (y,x,modes) optionally 4D (y,x,modes, scenatios)
TYPE:
|
this_pos_array
|
Integer beam postions in pixels [[y0,x0],.. [yn, xn]]. Note: units are pixels, not angstrom!
TYPE:
|
this_pos_correction
|
Float sub-pixel postions for more precise beam shift. Note: units are pixels, not angstrom!
TYPE:
|
this_tilt_array
|
Beam tilts in radians, shape should be (N_measurements, 6), where first two tilts are applied before the sample, second and third are applied inside (tilted propagator) and two last are applied after the sample
TYPE:
|
this_tilts_correction
|
legacy paramter, actually is not really required. It is a correction that is added to the tilts array.
TYPE:
|
this_distances
|
either just one value for a common slice spacing or list of values for each slice. If object has N slices, it should have N-1 entries.
TYPE:
|
measured_array
|
array or h5-dataset with diffraction patterns. Should be 3D, [N_measurements, y,x]
TYPE:
|
algorithm_type
|
string indicating the loss function (error metric)
|
this_wavelength
|
Electron wavelength in Angstrom
TYPE:
|
this_step_probe
|
do you refine the beam?
TYPE:
|
this_step_obj
|
do you refine the object?
TYPE:
|
this_step_pos_correction
|
do you refine the positions?
|
this_step_tilts
|
do you refine the tilts?
TYPE:
|
masks
|
optional, if the data is compressed, you should provide the 3D array with virtual detectors [N_detectors, y,x].
TYPE:
|
pixel_size_x_A
|
real-space pixel size in x-direction (Angstrom).
TYPE:
|
pixel_size_y_A
|
real-space pixel size in y-direction (Angstrom).
TYPE:
|
recon_type
|
"far_field" or "near_field". Changes the exit-wave propagation regime.
TYPE:
|
Cs
|
Spherical aberration (Angstrom). Only needed for near-field propagation.
TYPE:
|
defocus_array
|
Array of exit-wave defocus values (Angstrom). Only needed for near-field propagation.
TYPE:
|
alpha_near_field
|
Flux-preserving correction for near-field propagation.
TYPE:
|
damping_cutoff_multislice
|
Cutoff (fraction smaller than 1) beyond which the Fouirer-space is cleaned.
TYPE:
|
smooth_rolloff
|
Smooth rolloff for Fourier masking
TYPE:
|
propmethod
|
string indicating the method for split-step integration
TYPE:
|
this_chopped_sequence
|
sequence of measruement indices used for loss and grad calculation (should be sorted)
TYPE:
|
load_one_by_one
|
boolean flag. should be True for lazy loading.
TYPE:
|
data_multiplier
|
multiplicative factor applied to data on the fly.
TYPE:
|
data_pad
|
padding factor applied to data on the fly.
TYPE:
|
phase_plate_in_h5
|
path to h5 dataset containing phase plates for each measurement.
TYPE:
|
this_loss_weight
|
weight applied to the main part of the loss
TYPE:
|
data_bin
|
binning factor applied to data on the fly
TYPE:
|
data_shift_vector
|
shift vector in pixels (y,x) applied to data on the fly
TYPE:
|
upsample_pattern
|
virtual "decompression" of the data used to enlarge the probe window
TYPE:
|
static_background
|
real-valued array descripting the square root of the static offset on the diffraction patterns.
TYPE:
|
this_step_static_background
|
do you refine the static background?
TYPE:
|
tilt_mode
|
flag for tilting
TYPE:
|
aberration_marker
|
TYPE:
|
probe_marker
|
TYPE:
|
aberrations_array
|
TYPE:
|
compute_batch
|
TYPE:
|
phase_only_obj
|
TYPE:
|
beam_current
|
TYPE:
|
this_beam_current_step
|
TYPE:
|
this_step_aberrations_array
|
TYPE:
|
default_float
|
TYPE:
|
default_complex
|
TYPE:
|
xp
|
TYPE:
|
is_first_epoch
|
TYPE:
|
scan_size
|
TYPE:
|
fast_axis_reg_weight_positions
|
TYPE:
|
slow_axis_reg_weight_positions
|
TYPE:
|
slow_axis_reg_weight_tilts
|
TYPE:
|
current_deformation_reg_weight_positions
|
TYPE:
|
current_deformation_reg_weight_tilts
|
TYPE:
|
fast_axis_reg_weight_tilts
|
TYPE:
|
aperture_mask
|
TYPE:
|
probe_reg_weight
|
TYPE:
|
current_window_weight
|
TYPE:
|
current_window
|
TYPE:
|
phase_norm_weight
|
TYPE:
|
abs_norm_weight
|
TYPE:
|
atv_weight
|
TYPE:
|
atv_q
|
TYPE:
|
atv_p
|
TYPE:
|
mixed_variance_weight
|
TYPE:
|
mixed_variance_sigma
|
TYPE:
|
smart_memory
|
do you want to prevent memory fragmentation? Makes the reconstrcution slightly slower
TYPE:
|
print_flag
|
verbodity level
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
loss
|
Total loss value.
TYPE:
|
sse
|
Sum of squared errors.
TYPE:
|
object_grad
|
Gradient of the loss with respect to the object.
TYPE:
|
probe_grad
|
Gradient of the loss with respect to the probe.
TYPE:
|
pos_grad
|
Gradient of the loss with respect to scan position corrections.
TYPE:
|
tilts_grad
|
Gradient of the loss with respect to tilts.
TYPE:
|
static_background_grad
|
Gradient of the loss with respect to static background.
TYPE:
|
aberrations_array_grad
|
Gradient of the loss with respect to aberration coefficients.
TYPE:
|
beam_current_grad
|
Gradient of the loss with respect to beam current.
TYPE:
|
constraint_contributions
|
Individual regularization loss terms added to the total loss.
TYPE:
|
scatteradd_probe
¶
Adds batched probe updates to their respective positions in the full probe array. This wrapper is needed to support older CuPy version.
| PARAMETER | DESCRIPTION |
|---|---|
full
|
Full probe gradient array.
TYPE:
|
indic
|
Indices specifying where to add each batch.
TYPE:
|
batches
|
Batched gradients to scatter-add.
TYPE:
|
scatteradd_abers
¶
Adds batched aberration updates to their respective positions in the full aberration array. This wrapper is needed to support older CuPy version.
| PARAMETER | DESCRIPTION |
|---|---|
full
|
Full aberration gradient array.
TYPE:
|
indic
|
Indices specifying where to add each batch.
TYPE:
|
batches
|
Batched gradients to scatter-add.
TYPE:
|
charge_flip
¶
Perform charge-flipping style object regularization to enhance phase and absorption contrast.
| PARAMETER | DESCRIPTION |
|---|---|
a
|
Complex object to regularize.
TYPE:
|
delta_phase
|
Phase threshold ratio.
TYPE:
|
delta_abs
|
Absorption threshold ratio.
TYPE:
|
beta_phase
|
Inversion multiplier for low-phase regions.
TYPE:
|
beta_abs
|
Inversion multiplier for low-absorption regions.
TYPE:
|
fancy_sigma
|
Tuple of atomic-shape gaussian kernel sigmas (for phase, absorption).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Regularized complex object. |
make_states_orthogonal
¶
Apply Gram-Schmidt orthogonalization to probe modes.
| PARAMETER | DESCRIPTION |
|---|---|
probe_states
|
Probe array with multiple modes.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Orthogonalized probe states. |
make_basis_orthogonal
¶
Orthogonalize a set of 1D basis vectors using Gram-Schmidt.
| PARAMETER | DESCRIPTION |
|---|---|
vectors
|
2D array of vectors to orthogonalize.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Orthogonalized basis. |
clear_missing_wedge
¶
Remove missing wedge artifacts by applying a cone filter in 3D FFT space.
| PARAMETER | DESCRIPTION |
|---|---|
obj
|
3D complex object.
TYPE:
|
px_size_x_A
|
Pixel size along x (Å).
TYPE:
|
px_size_y_A
|
Pixel size along y (Å).
TYPE:
|
slice_distance
|
Distance between slices (Å).
TYPE:
|
beta_wedge
|
Cone sharpness parameter.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Filtered object with reduced missing wedge effects. |
compute_fast_axis_constraint_on_grid
¶
Apply second-order TV regularization along the fast scan axis.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
Positions or tilts to regularize.
TYPE:
|
scan_size
|
Size of the scan grid.
TYPE:
|
tv_reg_weight
|
Regularization weight.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Value of the regularization term.
TYPE:
|
grad
|
Gradient of the regularization.
TYPE:
|
compute_slow_axis_constraint_on_grid
¶
Apply second-order TV regularization along the slow scan axis.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
Positions or tilts to regularize.
TYPE:
|
scan_size
|
Size of the scan grid.
TYPE:
|
tv_reg_weight
|
Regularization weight.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Regularization loss.
TYPE:
|
grad
|
Gradient with respect to the input.
TYPE:
|
compute_deformation_constraint_on_grid
¶
Penalize deviations from affine transformations in local scan patches.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
Grid to regularize (positions or tilts).
TYPE:
|
scan_size
|
Dimensions of the scan.
TYPE:
|
reg_weight
|
Regularization weight.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Regularization loss.
TYPE:
|
grad
|
Gradient of the loss with respect to the grid.
TYPE:
|
compute_full_l1_constraint
¶
Apply L1 norm regularization to the object's phase and absorption.
| PARAMETER | DESCRIPTION |
|---|---|
object
|
Complex object array.
TYPE:
|
abs_norm_weight
|
Weight for absorption norm.
TYPE:
|
phase_norm_weight
|
Weight for phase norm.
TYPE:
|
grad_mask
|
Mask to restrict gradient computation.
TYPE:
|
return_direction
|
If True, return the gradient.
TYPE:
|
smart_memory
|
Memory-efficient option.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Regularization loss.
TYPE:
|
grad
|
Gradient if
TYPE:
|
compute_window_constraint
¶
Penalize probe values outside a predefined window region in real-space.
| PARAMETER | DESCRIPTION |
|---|---|
to_reg_probe
|
Complex probe array.
TYPE:
|
current_window
|
Window mask.
TYPE:
|
current_window_weight
|
Weight of the constraint.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Window constraint loss.
TYPE:
|
reg_grad
|
Gradient of the loss with respect to the probe.
TYPE:
|
compute_probe_constraint
¶
Apply reciprocal space constraint to the probe using an aperture mask. Penalize probe values outside an aperture.
| PARAMETER | DESCRIPTION |
|---|---|
to_reg_probe
|
Complex probe array.
TYPE:
|
aperture
|
Binary mask or scalar defining aperture radius.
TYPE:
|
weight
|
Regularization weight.
TYPE:
|
return_direction
|
If True, return the gradient.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Loss from masked frequency components.
TYPE:
|
probe_fft
|
Gradient of the constraint if requested.
TYPE:
|
compute_atv_constraint
¶
Apply adaptive total variation (ATV) regularization to the object.
| PARAMETER | DESCRIPTION |
|---|---|
obj
|
Complex object.
TYPE:
|
atv_weight
|
Regularization weight.
TYPE:
|
atv_q
|
q-norm parameter.
TYPE:
|
atv_p
|
p-norm parameter.
TYPE:
|
pixel_size_x_A
|
Pixel size along x (Å).
TYPE:
|
pixel_size_y_A
|
Pixel size along y (Å).
TYPE:
|
atv_grad_mask
|
Optional gradient mask.
TYPE:
|
return_direction
|
If True, return the gradient.
TYPE:
|
smart_memory
|
If True, use memory-efficient computation.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
ATV regularization value.
TYPE:
|
dR_dTerm
|
Gradient with respect to the object.
TYPE:
|
compute_missing_wedge_constraint
¶
Enforce missing wedge constraint in 3D reciprocal space.
| PARAMETER | DESCRIPTION |
|---|---|
obj
|
3D complex object.
TYPE:
|
px_size_x_A
|
Pixel size along x (Å).
TYPE:
|
px_size_y_A
|
Pixel size along y (Å).
TYPE:
|
slice_distance
|
Slice spacing (Å).
TYPE:
|
beta_wedge
|
Cone sharpness.
TYPE:
|
wegde_mu
|
Regularization weight.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
loss_term
|
Regularization loss.
TYPE:
|
grad_obj
|
Gradient of the loss with respect to the object.
TYPE:
|
compute_mixed_object_variance_constraint
¶
Regularize variance across object modes by penalizing their differences.
| PARAMETER | DESCRIPTION |
|---|---|
this_obj
|
Complex object array with multiple modes.
TYPE:
|
weight
|
Regularization strength.
TYPE:
|
sigma
|
Smoothing kernel width in frequency space.
TYPE:
|
return_direction
|
If True, return the gradient.
TYPE:
|
smart_memory
|
Use memory-efficient FFT loops.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
reg_term
|
Mixed variance loss.
TYPE:
|
grad
|
Gradient with respect to the object if
TYPE:
|
pypty.multislice_core¶
multislice
¶
Simulate multislice wave propagation using a classic split-step integrator (2nd order precision with respect to slice thickness if beam is optimized).
| PARAMETER | DESCRIPTION |
|---|---|
full_probe
|
Probe wavefunction with shape [N_batch, y,x, modes]
TYPE:
|
this_obj_chopped
|
Object slices with shape [N_batch, y,x, z, modes].
TYPE:
|
num_slices
|
Number of object slices.
TYPE:
|
n_obj_modes
|
Number of object modes.
TYPE:
|
n_probe_modes
|
Number of probe modes.
TYPE:
|
this_distances
|
Slice thicknesses.
TYPE:
|
this_wavelength
|
Electron wavelength.
TYPE:
|
q2
|
Spatial frequency grids.
TYPE:
|
qx
|
Spatial frequency grids.
TYPE:
|
qy
|
Spatial frequency grids.
TYPE:
|
exclude_mask
|
Mask to exclude undesired frequencies.
TYPE:
|
is_single_dist
|
If True, use the same distance for all slices.
TYPE:
|
this_tan_x
|
Beam tilts with shape N_batch
TYPE:
|
this_tan_y
|
Beam tilts with shape N_batch
TYPE:
|
damping_cutoff_multislice
|
Damping frequency cutoff.
TYPE:
|
smooth_rolloff
|
Rolloff rate for the damping filter.
TYPE:
|
master_propagator_phase_space
|
Full propagator in Fourier space (optional).
TYPE:
|
half_master_propagator_phase_space
|
Half-step propagator (optional).
TYPE:
|
mask_clean
|
Clean propagation mask.
TYPE:
|
waves_multislice
|
This array contains interediate exit-waves
TYPE:
|
wave
|
This array contains final exit-wave
TYPE:
|
default_float
|
Numerical types.
TYPE:
|
default_complex
|
Numerical types.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
waves_multislice
|
Multislice stack of propagated waves.
TYPE:
|
wave
|
Final exit wave.
TYPE:
|
multislice_grads
¶
Compute gradients for classic multislice propagation model (object, probe, and tilts).
| PARAMETER | DESCRIPTION |
|---|---|
dLoss_dP_out
|
Gradient of the loss with respect to the final propagated wave.
TYPE:
|
waves_multislice
|
Intermediate wave stack from the forward multislice pass.
TYPE:
|
this_obj_chopped
|
4D sliced object [batch, y, x, z, modes].
TYPE:
|
object_grad
|
Gradient accumulator for object slices.
TYPE:
|
tilts_grad
|
Accumulator for tilt gradients.
TYPE:
|
is_single_dist
|
If True, slice distances are constant.
TYPE:
|
this_distances
|
Per-slice thicknesses.
TYPE:
|
exclude_mask
|
Frequency mask for FFT operations.
TYPE:
|
this_wavelength
|
Probe wavelength (Å).
TYPE:
|
q2
|
Spatial frequency grids.
TYPE:
|
qx
|
Spatial frequency grids.
TYPE:
|
qy
|
Spatial frequency grids.
TYPE:
|
this_tan_x
|
Beam tilt values per batch.
TYPE:
|
this_tan_y
|
Beam tilt values per batch.
TYPE:
|
num_slices
|
Number of slices.
TYPE:
|
n_obj_modes
|
Number of object modes.
TYPE:
|
tiltind
|
Index in tilt update array.
TYPE:
|
master_propagator_phase_space
|
Full Fourier propagation kernel.
TYPE:
|
this_step_tilts
|
Whether tilt gradient is updated.
TYPE:
|
damping_cutoff_multislice
|
Damping cutoff for high-frequency noise.
TYPE:
|
smooth_rolloff
|
Width of damping transition.
TYPE:
|
tilt_mode
|
Mode selector for tilt optimization.
TYPE:
|
compute_batch
|
Current batch size.
TYPE:
|
mask_clean
|
FFT domain mask.
TYPE:
|
this_step_probe
|
Whether to compute probe gradient.
TYPE:
|
this_step_obj
|
Whether to compute object gradient.
TYPE:
|
this_step_pos_correction
|
(Unused) Flag for positional corrections.
TYPE:
|
masked_pixels_y
|
Indices for applying gradients to global object.
TYPE:
|
masked_pixels_x
|
Indices for applying gradients to global object.
TYPE:
|
default_float
|
Floating-point type.
TYPE:
|
default_complex
|
Complex type.
TYPE:
|
helper_flag_4
|
If True, return probe gradient; else return None.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
object_grad
|
Gradient for object slices.
TYPE:
|
interm_probe_grad
|
Gradient for input probe (if helper_flag_4 is True).
TYPE:
|
tilts_grad
|
Updated tilt gradient.
TYPE:
|
better_multislice
¶
Simulate multislice wave propagation using an additive split-step method (5th order precision with respect to slice thickness).
| PARAMETER | DESCRIPTION |
|---|---|
full_probe
|
Probe wavefunction with shape [N_batch, y,x, modes]
TYPE:
|
this_obj_chopped
|
Object slices with shape [N_batch, y,x, z, modes].
TYPE:
|
num_slices
|
Number of object slices.
TYPE:
|
n_obj_modes
|
Number of object modes.
TYPE:
|
n_probe_modes
|
Number of probe modes.
TYPE:
|
this_distances
|
Slice thicknesses.
TYPE:
|
this_wavelength
|
Electron wavelength.
TYPE:
|
q2
|
Spatial frequency grids.
TYPE:
|
qx
|
Spatial frequency grids.
TYPE:
|
qy
|
Spatial frequency grids.
TYPE:
|
exclude_mask
|
Mask to exclude undesired frequencies.
TYPE:
|
is_single_dist
|
If True, use the same distance for all slices.
TYPE:
|
this_tan_x
|
Beam tilts with shape N_batch
TYPE:
|
this_tan_y
|
Beam tilts with shape N_batch
TYPE:
|
damping_cutoff_multislice
|
Damping frequency cutoff.
TYPE:
|
smooth_rolloff
|
Rolloff rate for the damping filter.
TYPE:
|
master_propagator_phase_space
|
Full propagator in Fourier space (optional).
TYPE:
|
half_master_propagator_phase_space
|
Half-step propagator (optional).
TYPE:
|
mask_clean
|
Clean propagation mask.
TYPE:
|
waves_multislice
|
This array contains interediate exit-waves
TYPE:
|
wave
|
This array contains final exit-wave
TYPE:
|
default_float
|
Numerical types.
TYPE:
|
default_complex
|
Numerical types.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
waves_multislice
|
Multislice stack of propagated waves.
TYPE:
|
wave
|
Final exit wave.
TYPE:
|
better_multislice_grads
¶
Compute gradients of object, probe, and tilts for the "better_multislice" wave propagation model.
| PARAMETER | DESCRIPTION |
|---|---|
dLoss_dP_out
|
Gradient of the loss with respect to the final exit wave.
TYPE:
|
waves_multislice
|
Stack of intermediate wavefields saved during the forward pass.
TYPE:
|
this_obj_chopped
|
The sliced object with shape [batch, y, x, z, modes].
TYPE:
|
object_grad
|
Gradient accumulator for the object slices.
TYPE:
|
tilts_grad
|
Gradient accumulator for the tilts.
TYPE:
|
is_single_dist
|
Whether all slices have the same thickness.
TYPE:
|
this_distances
|
Thickness per slice.
TYPE:
|
exclude_mask
|
Frequency mask used in propagation.
TYPE:
|
this_wavelength
|
Wavelength of the probe in Ångströms.
TYPE:
|
q2
|
Spatial frequency grids.
TYPE:
|
qx
|
Spatial frequency grids.
TYPE:
|
qy
|
Spatial frequency grids.
TYPE:
|
this_tan_x
|
Beam tilt values per batch.
TYPE:
|
this_tan_y
|
Beam tilt values per batch.
TYPE:
|
num_slices
|
Number of slices in the object.
TYPE:
|
n_probe_modes
|
Number of probe modes.
TYPE:
|
n_obj_modes
|
Number of object modes.
TYPE:
|
tiltind
|
Index for updating
TYPE:
|
this_step_tilts
|
Whether to update tilts (0 = off).
TYPE:
|
master_propagator_phase_space
|
Full propagator for the current slice.
TYPE:
|
half_master_propagator_phase_space
|
Half-step propagator.
TYPE:
|
damping_cutoff_multislice
|
Cutoff for high frequencies in damping.
TYPE:
|
smooth_rolloff
|
Smoothing width for damping filter.
TYPE:
|
tilt_mode
|
Specifies which tilts to optimize.
TYPE:
|
compute_batch
|
Number of scan positions processed in batch.
TYPE:
|
mask_clean
|
FFT mask used to remove unstable frequencies.
TYPE:
|
masked_pixels_y
|
Indices to scatter object gradients into global coordinates.
TYPE:
|
masked_pixels_x
|
Indices to scatter object gradients into global coordinates.
TYPE:
|
default_float
|
Floating point precision.
TYPE:
|
default_complex
|
Complex precision.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
object_grad
|
Updated gradient of the object slices.
TYPE:
|
interm_probe_grad
|
Gradient of the probe (summed over object modes).
TYPE:
|
tilts_grad
|
Updated tilt gradients.
TYPE:
|
yoshida_multislice
¶
Simulate multislice wave propagation using an yoshida integrator (5th order precision with respect to slice thickness).
| PARAMETER | DESCRIPTION |
|---|---|
full_probe
|
Probe wavefunction with shape [N_batch, y,x, modes]
TYPE:
|
this_obj_chopped
|
Object slices with shape [N_batch, y,x, z, modes].
TYPE:
|
num_slices
|
Number of object slices.
TYPE:
|
n_obj_modes
|
Number of object modes.
TYPE:
|
n_probe_modes
|
Number of probe modes.
TYPE:
|
this_distances
|
Slice thicknesses.
TYPE:
|
this_wavelength
|
Electron wavelength.
TYPE:
|
q2
|
Spatial frequency grids.
TYPE:
|
qx
|
Spatial frequency grids.
TYPE:
|
qy
|
Spatial frequency grids.
TYPE:
|
exclude_mask
|
Mask to exclude undesired frequencies.
TYPE:
|
is_single_dist
|
If True, use the same distance for all slices.
TYPE:
|
this_tan_x
|
Beam tilts with shape N_batch
TYPE:
|
this_tan_y
|
Beam tilts with shape N_batch
TYPE:
|
damping_cutoff_multislice
|
Damping frequency cutoff.
TYPE:
|
smooth_rolloff
|
Rolloff rate for the damping filter.
TYPE:
|
master_propagator_phase_space
|
Full propagator in Fourier space (optional).
TYPE:
|
half_master_propagator_phase_space
|
Half-step propagator (optional).
TYPE:
|
mask_clean
|
Clean propagation mask.
TYPE:
|
waves_multislice
|
This array contains interediate exit-waves
TYPE:
|
wave
|
This array contains final exit-wave
TYPE:
|
default_float
|
Numerical types.
TYPE:
|
default_complex
|
Numerical types.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
waves_multislice
|
Multislice stack of propagated waves.
TYPE:
|
wave
|
Final exit wave.
TYPE:
|
yoshida_multislice_grads
¶
Compute gradients for object, probe, and tilt parameters using Yoshida multislice propagation.
| PARAMETER | DESCRIPTION |
|---|---|
dLoss_dP_out
|
Gradient of the loss with respect to the output wave.
TYPE:
|
waves_multislice
|
Stored intermediate wavefields from forward Yoshida multislice pass.
TYPE:
|
this_obj_chopped
|
Object slices with shape [batch, y, x, z, modes].
TYPE:
|
object_grad
|
Gradient buffer for object update.
TYPE:
|
tilts_grad
|
Gradient buffer for tilt update.
TYPE:
|
is_single_dist
|
Whether slice distances are constant.
TYPE:
|
this_distances
|
Thickness of each slice.
TYPE:
|
exclude_mask
|
FFT mask for excluding unstable frequencies.
TYPE:
|
this_wavelength
|
Probe wavelength in Ångströms.
TYPE:
|
q2
|
FFT spatial frequency grids.
TYPE:
|
qx
|
FFT spatial frequency grids.
TYPE:
|
qy
|
FFT spatial frequency grids.
TYPE:
|
this_tan_x
|
Beam tilts (tangent of the angle).
TYPE:
|
this_tan_y
|
Beam tilts (tangent of the angle).
TYPE:
|
num_slices
|
Number of object slices.
TYPE:
|
n_probe_modes
|
Number of probe modes.
TYPE:
|
n_obj_modes
|
Number of object modes.
TYPE:
|
tiltind
|
Index of current tilt in
TYPE:
|
this_step_tilts
|
Whether tilt updates are enabled.
TYPE:
|
master_propagator_phase_space
|
Full propagation kernel in Fourier domain.
TYPE:
|
half_master_propagator_phase_space
|
Half-step propagation kernel.
TYPE:
|
damping_cutoff_multislice
|
Frequency cutoff for damping high frequencies.
TYPE:
|
smooth_rolloff
|
Rolloff profile width for damping.
TYPE:
|
tilt_mode
|
Determines which tilt parameters to optimize.
TYPE:
|
compute_batch
|
Number of scan points in the current batch.
TYPE:
|
mask_clean
|
Fourier domain mask to stabilize calculations.
TYPE:
|
masked_pixels_y
|
Indices for inserting gradients into global object.
TYPE:
|
masked_pixels_x
|
Indices for inserting gradients into global object.
TYPE:
|
default_float
|
Float precision.
TYPE:
|
default_complex
|
Complex precision.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
object_grad
|
Updated object gradient.
TYPE:
|
interm_probe_grad
|
Gradient of the probe (combined over object modes).
TYPE:
|
tilts_grad
|
Updated tilt gradient.
TYPE:
|
scatteradd
¶
Adds batched object updates to their respective positions in the full object array. This wrapper is needed to support older CuPy versions.
| PARAMETER | DESCRIPTION |
|---|---|
full
|
Full object gradient array.
TYPE:
|
masky
|
Index array for the y-axis.
TYPE:
|
maskx
|
Index array for the x-axis.
TYPE:
|
chop
|
Batched gradients to scatter-add.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
pypty.fft¶
fftfreq
¶
Wrapper for fftfreq function.
| PARAMETER | DESCRIPTION |
|---|---|
length
|
Length of the output array.
TYPE:
|
sampling
|
Sample spacing (default is 1).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Discrete Fourier Transform sample frequencies. |
ifftfreq
¶
Wrapper for ifftfreq function.
| PARAMETER | DESCRIPTION |
|---|---|
length
|
Length of the output array.
TYPE:
|
sampling
|
Sample spacing (default is 1).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Discrete inverse Fourier Transform sample frequencies. |
fftshift
¶
Wrapper for fftshift function.
| PARAMETER | DESCRIPTION |
|---|---|
array
|
Input array to be shifted.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Shifted array. |
ifftshift
¶
Wrapper for ifftshift function.
| PARAMETER | DESCRIPTION |
|---|---|
array
|
Input array to be inverse shifted.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Inverse shifted array. |
shift_fft2
¶
Wrapper for xp.fft.fftshift(xp.fft.fft2(...)) functions.
| PARAMETER | DESCRIPTION |
|---|---|
arr
|
Input array to be transformed.
TYPE:
|
axes
|
Axes over which to compute the FFT (default is (0, 1)).
TYPE:
|
overwrite_x
|
If True, allow overwriting the input array (default is False).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
2D Fourier Transform of the input array, shifted. |
fft2
¶
Wrapper for fft2 function.
| PARAMETER | DESCRIPTION |
|---|---|
arr
|
Input array to be transformed.
TYPE:
|
axes
|
Axes over which to compute the FFT (default is (0, 1)).
TYPE:
|
overwrite_x
|
If True, allow overwriting the input array (default is False).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
2D Fourier Transform of the input array. |
ifft2
¶
Wrapper for ifft2 function.
| PARAMETER | DESCRIPTION |
|---|---|
arr
|
Input array to be transformed.
TYPE:
|
axes
|
Axes over which to compute the inverse FFT (default is (0, 1)).
TYPE:
|
overwrite_x
|
If True, allow overwriting the input array (default is False).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
2D inverse Fourier Transform of the input array. |
ifft2_ishift
¶
Wrapper for xp.fft.ifft2(xp.fft.ifftshift(...)) function.
| PARAMETER | DESCRIPTION |
|---|---|
arr
|
Input array to be transformed.
TYPE:
|
axes
|
Axes over which to compute the inverse FFT (default is (0, 1)).
TYPE:
|
overwrite_x
|
If True, allow overwriting the input array (default is False).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
2D inverse Fourier Transform of the input array, after shifting. |
shift_fftn
¶
Wrapper for xp.fft.fftshift(xp.fft.fftn(...)) function.
| PARAMETER | DESCRIPTION |
|---|---|
arr
|
Input array to be transformed.
TYPE:
|
axes
|
Axes over which to compute the FFT (default is (0, 1, 2)).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
N-dimensional Fourier Transform of the input array, shifted. |
ifftn_ishift
¶
Wrapper for xp.fft.ifftn(xp.fft.ifftshift(...)) function.
| PARAMETER | DESCRIPTION |
|---|---|
arr
|
Input array to be transformed.
TYPE:
|
axes
|
Axes over which to compute the inverse FFT (default is (0, 1, 2)).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
N-dimensional inverse Fourier Transform of the input array, after shifting. |
ifftn
¶
Wrapper for ifftn function.
| PARAMETER | DESCRIPTION |
|---|---|
arr
|
Input array to be transformed.
TYPE:
|
axes
|
Axes over which to compute the inverse FFT (default is (0, 1, 2)).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
N-dimensional inverse Fourier Transform of the input array. |
fftn
¶
Wrapper for fftn function.
| PARAMETER | DESCRIPTION |
|---|---|
arr
|
Input array to be transformed.
TYPE:
|
axes
|
Axes over which to compute the FFT (default is (0, 1, 2)).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
N-dimensional Fourier Transform of the input array. |
pypty.utils¶
fourier_clean_3d
¶
Apply a 3D Fourier filter to the input array.
| PARAMETER | DESCRIPTION |
|---|---|
array
|
Input 3D array to be filtered.
TYPE:
|
cutoff
|
Cutoff frequency (default is 0.66).
TYPE:
|
mask
|
Predefined mask to apply. If None, a mask is generated.
TYPE:
|
rolloff
|
Rolloff parameter for smoothing the mask (default is 0).
TYPE:
|
default_float
|
Data type for computations (default is cp.float32).
TYPE:
|
xp
|
Array module (default is cp).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The filtered array after applying the Fourier filter. |
fourier_clean
¶
Apply a Fourier filter to the input array. Supports 2D or 3D arrays.
| PARAMETER | DESCRIPTION |
|---|---|
array
|
Input array (2D or 3D) to be filtered.
TYPE:
|
cutoff
|
Cutoff frequency (default is 0.66).
TYPE:
|
mask
|
Predefined mask to apply. If None, a mask is generated.
TYPE:
|
rolloff
|
Rolloff parameter for smoothing the mask (default is 0).
TYPE:
|
default_float
|
Data type for computations (default is cp.float32).
TYPE:
|
xp
|
Array module (default is cp).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The filtered array after applying the Fourier filter. |
create_spatial_frequencies
¶
Generate spatial frequency grids and corresponding masks for multislice simulations.
| PARAMETER | DESCRIPTION |
|---|---|
px
|
Pixel size in the x-direction.
TYPE:
|
py
|
Pixel size in the y-direction.
TYPE:
|
shape
|
Size of the grid.
TYPE:
|
damping_cutoff_multislice
|
Damping cutoff factor for multislice simulations.
TYPE:
|
smooth_rolloff
|
Smoothing rolloff parameter.
TYPE:
|
default_float
|
Data type for computations.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Tuple containing: - q2: 2D array of squared spatial frequencies. - qx: 2D array of spatial frequencies in x. - qy: 2D array of spatial frequencies in y. - exclude_mask: Mask in Fourier space. - exclude_mask_ishift: Unshifted mask. |
shift_probe_fourier
¶
Shift a probe in Fourier space by applying a phase ramp.
| PARAMETER | DESCRIPTION |
|---|---|
probe
|
The input probe array.
TYPE:
|
shift_px
|
Shift in pixels (y, x).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Tuple containing the shifted probe, the phase mask, the Fourier transform of the probe, and the spatial frequency grids (maskx, masky). |
generate_mask_for_grad_from_pos
¶
Construct a binary mask from given positions and footprint dimensions.
| PARAMETER | DESCRIPTION |
|---|---|
shapex
|
Width of the mask.
TYPE:
|
shapey
|
Height of the mask.
TYPE:
|
positions_list
|
List of (y, x) positions where the mask should be activated.
TYPE:
|
shape_footprint_x
|
Footprint width.
TYPE:
|
shape_footprint_y
|
Footprint height.
TYPE:
|
shrink
|
Shrink factor to adjust the footprint (default is 0).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The constructed binary mask. |
complex_grad_to_phase_grad
¶
Convert a Wirtinger derivative to the gradient with respect to the phase.
| PARAMETER | DESCRIPTION |
|---|---|
grad
|
The Wirtinger derivative (dL/dz*).
TYPE:
|
array
|
The complex array (z = |z| exp(i*phase)).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The phase gradient (dL/dp). |
complex_grad_to_phase_abs_grad
¶
Compute the phase gradient and negative amplitude gradient from a complex gradient.
| PARAMETER | DESCRIPTION |
|---|---|
grad
|
The Wirtinger derivative (dL/dz*).
TYPE:
|
array
|
The complex array (z = exp(-a + i*phase)).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
tuple of array_like
|
A tuple containing: - Phase gradient (dL/dp). - Negative amplitude gradient (dL/da). |
complex_grad_to_mag_grad
¶
Calculate a magnitude gradient from a complex gradient and separate magnitude and phase arrays.
| PARAMETER | DESCRIPTION |
|---|---|
grad
|
The complex gradient.
TYPE:
|
abs
|
The magnitude array.
TYPE:
|
phase
|
The phase array.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The magnitude gradient. |
construct_update_abs_proto_phase
¶
Compute object updates projected along phase gradients.
| PARAMETER | DESCRIPTION |
|---|---|
object_grad
|
The gradient of the object.
TYPE:
|
obj
|
The current object array.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The computed update for the object. |
wolfe_1
¶
Check the Armijo condition (Wolfe condition 1) for line search.
| PARAMETER | DESCRIPTION |
|---|---|
value
|
The current function value.
TYPE:
|
new_value
|
The function value after the step.
TYPE:
|
d_value
|
The directional derivative at the current point.
TYPE:
|
step
|
Step size.
TYPE:
|
wolfe_c1
|
Armijo condition constant (default is 0.5).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
True if the condition is satisfied, False otherwise. |
wolfe_2
¶
Check the curvature condition (Wolfe condition 2) for line search.
| PARAMETER | DESCRIPTION |
|---|---|
d_value
|
The directional derivative at the current point.
TYPE:
|
new_d_value
|
The directional derivative after the step.
TYPE:
|
wolfe_c2
|
Curvature condition constant (default is 0.9).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
True if the condition is satisfied, False otherwise. |
upsample_something_3d
¶
Upsample a 3D array along the last two axes.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
The 3D array to be upsampled.
TYPE:
|
upsample
|
Upsampling factor.
TYPE:
|
scale
|
If True, scales the upsampled result to conserve total sum (default is True).
TYPE:
|
xp
|
Array module, e.g., numpy or cupy (default is numpy).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The upsampled 3D array. |
downsample_something_3d
¶
Downsample a 3D array along the last two axes.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
The 3D array to be downsampled.
TYPE:
|
upsample
|
Downsampling factor.
TYPE:
|
xp
|
Array module, e.g., numpy or cupy.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The downsampled 3D array. |
upsample_something
¶
Upsample a 2D array.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
The 2D array to be upsampled.
TYPE:
|
upsample
|
Upsampling factor.
TYPE:
|
scale
|
If True, scales the result to conserve total sum (default is True).
TYPE:
|
xp
|
Array module (default is numpy).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The upsampled array. |
downsample_something
¶
Downsample a 2D array.
| PARAMETER | DESCRIPTION |
|---|---|
something
|
The 2D array to be downsampled.
TYPE:
|
upsample
|
Downsampling factor.
TYPE:
|
xp
|
Array module, e.g., numpy or cupy.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The downsampled array. |
preprocess_dataset
¶
Apply preprocessing steps to the dataset including shifting, binning, padding, and scaling.
| PARAMETER | DESCRIPTION |
|---|---|
dataset
|
The input dataset.
TYPE:
|
load_one_by_one
|
Whether data is loaded incrementally.
TYPE:
|
algorithm_type
|
Type of reconstruction algorithm.
TYPE:
|
recon_type
|
Type of reconstruction (e.g., near_field, far_field).
TYPE:
|
data_shift_vector
|
Vector indicating pixel shift in y and x.
TYPE:
|
data_bin
|
Binning factor.
TYPE:
|
data_pad
|
Padding size.
TYPE:
|
upsample_pattern
|
Upsampling factor for the pattern.
TYPE:
|
data_multiplier
|
Factor to scale data intensity.
TYPE:
|
xp
|
Array module, e.g., numpy or cupy.
TYPE:
|
force_pad
|
If True, apply forced padding.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Tuple containing: - preprocessed dataset - data_shift_vector - data_bin - data_pad - data_multiplier |
get_window
¶
Create a circular cosine-tapered window mask.
| PARAMETER | DESCRIPTION |
|---|---|
shape
|
Size of the square window.
TYPE:
|
r0
|
Inner radius where tapering begins (normalized).
TYPE:
|
r_max
|
Outer radius where mask falls to zero (normalized).
TYPE:
|
inverted
|
If True, returns 1 - mask (default is True).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
A 2D mask array of the specified shape. |
convert_num_to_nmab
¶
Convert a number of aberration terms to (n, m, ab) indices based on Krivanek notation.
| PARAMETER | DESCRIPTION |
|---|---|
num_abs
|
Number of aberration coefficients.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
tuple of lists
|
Lists of n, m, and ab strings ('', 'a', or 'b') for each aberration mode. |
nmab_to_strings
¶
Convert aberration indices into string identifiers in Krivanek notation.
| PARAMETER | DESCRIPTION |
|---|---|
possible_n
|
List of radial indices.
TYPE:
|
possible_m
|
List of azimuthal indices.
TYPE:
|
possible_ab
|
List of aberration mode types ('', 'a', 'b').
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list of str
|
List of formatted aberration identifiers like 'C30a', 'C11', etc. |
get_ctf_matrix
¶
Generate a matrix of phase contributions for all aberration modes.
| PARAMETER | DESCRIPTION |
|---|---|
kx
|
Spatial frequency in x-direction.
TYPE:
|
ky
|
Spatial frequency in y-direction.
TYPE:
|
num_abs
|
Number of aberration coefficients.
TYPE:
|
wavelength
|
Electron wavelength.
TYPE:
|
xp
|
Array module (default is cupy).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
list of Zernike polynomials (num_abs, height, width) with phase contributions. |
get_ctf
¶
Compute the scalar contrast transfer function (CTF) from aberrations.
| PARAMETER | DESCRIPTION |
|---|---|
aberrations
|
List of aberration coefficients.
TYPE:
|
kx
|
Spatial frequency in x-direction.
TYPE:
|
ky
|
Spatial frequency in y-direction.
TYPE:
|
wavelength
|
Electron wavelength.
TYPE:
|
angle_offset
|
Additional rotation angle in radians (default is 0).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The computed CTF. |
get_ctf_derivatives
¶
Compute spatial derivatives of the CTF with respect to kx and ky.
| PARAMETER | DESCRIPTION |
|---|---|
aberrations
|
List of aberration coefficients.
TYPE:
|
kx
|
Spatial frequency in x-direction.
TYPE:
|
ky
|
Spatial frequency in y-direction.
TYPE:
|
wavelength
|
Electron wavelength.
TYPE:
|
angle_offset
|
Additional rotation angle (default is 0).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
tuple of ndarray
|
Derivatives of CTF with respect to kx and ky. |
get_ctf_gradient_rotation_angle
¶
Compute the gradient of the phase with respect to rotation angle.
| PARAMETER | DESCRIPTION |
|---|---|
aberrations
|
List of aberration coefficients.
TYPE:
|
kx
|
Spatial frequency in x-direction.
TYPE:
|
ky
|
Spatial frequency in y-direction.
TYPE:
|
wavelength
|
Electron wavelength.
TYPE:
|
angle_offset
|
Additional angular offset (default is 0).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
tuple of ndarray
|
Derivatives of the CTF gradient in x and y directions with respect to angular change. |
apply_defocus_probe
¶
Apply a defocus phase shift to a probe in Fourier space.
| PARAMETER | DESCRIPTION |
|---|---|
probe
|
The input probe wavefunction.
TYPE:
|
distance
|
Defocus distance in meters.
TYPE:
|
acc_voltage
|
Acceleration voltage in kiloelectronvolts (keV).
TYPE:
|
pixel_size_x_A
|
Pixel size along x in angstroms.
TYPE:
|
pixel_size_y_A
|
Pixel size along y in angstroms.
TYPE:
|
default_complex
|
Complex data type for computation.
TYPE:
|
default_float
|
Float data type for computation.
TYPE:
|
xp
|
Numerical backend (NumPy or CuPy).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The defocused probe. |
padfft
¶
Pad the input array in Fourier space by padding its FFT.
| PARAMETER | DESCRIPTION |
|---|---|
array
|
Input array to be padded.
TYPE:
|
pad
|
Number of pixels to pad on each side.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The padded array in spatial domain. |
padprobetodatafarfield
¶
Pad or crop a probe in Fourier space to match far-field data dimensions.
| PARAMETER | DESCRIPTION |
|---|---|
probe
|
The probe wavefunction.
TYPE:
|
measured_data_shape
|
Shape of the measured data.
TYPE:
|
data_pad
|
Padding applied to the data.
TYPE:
|
upsample_pattern
|
Upsampling factor used in the reconstruction.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Adjusted probe wavefunction. |
padprobetodatanearfield
¶
Pad or crop a probe for near-field reconstruction.
This function adjusts the probe wavefunction by padding or cropping it to match the near-field measured data dimensions after upsampling and padding.
| PARAMETER | DESCRIPTION |
|---|---|
probe
|
The input probe wavefunction.
TYPE:
|
measured_data_shape
|
Shape of the measured data.
TYPE:
|
data_pad
|
Padding size applied to the data.
TYPE:
|
upsample_pattern
|
Upsampling factor applied to the measured data.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The adjusted probe wavefunction. |
save_updated_arrays
¶
Save current reconstruction state and log loss metrics during training.
This function saves checkpoints for object, probe, tilts, scan positions, static background, aberration coefficients, and beam current if specified. It also logs loss and constraint contributions in a CSV file if logging is enabled.
| PARAMETER | DESCRIPTION |
|---|---|
output_folder
|
Directory where files will be saved.
TYPE:
|
epoch
|
Current epoch number.
TYPE:
|
current_probe_step
|
Whether to save the current probe.
TYPE:
|
current_probe_pos_step
|
Whether to save current scan positions.
TYPE:
|
current_tilts_step
|
Whether to save current tilts.
TYPE:
|
current_obj_step
|
Whether to save the current object.
TYPE:
|
obj
|
Object array to save.
TYPE:
|
probe
|
Probe array to save.
TYPE:
|
tilts_correction
|
Tilt correction values.
TYPE:
|
full_pos_correction
|
Sub-pixel scan position correction.
TYPE:
|
positions
|
Integer scan positions.
TYPE:
|
tilts
|
Original tilt values.
TYPE:
|
static_background
|
Static background array.
TYPE:
|
current_aberrations_array_step
|
Whether to save aberration array.
TYPE:
|
current_static_background_step
|
Whether to save static background.
TYPE:
|
count
|
Not used inside the function.
TYPE:
|
current_loss
|
Current loss value.
TYPE:
|
current_sse
|
Current sum of squared errors.
TYPE:
|
aberrations
|
Array of aberration coefficients.
TYPE:
|
beam_current
|
Array of beam current values.
TYPE:
|
current_beam_current_step
|
Whether to save beam current.
TYPE:
|
save_flag
|
Whether to trigger checkpoint saving.
TYPE:
|
save_loss_log
|
Whether to log loss. If set to 2, log full breakdown of constraints.
TYPE:
|
constraint_contributions
|
List of constraint term contributions to the loss.
TYPE:
|
actual_step
|
Step size applied in the optimizer.
TYPE:
|
count_linesearch
|
Number of line search iterations.
TYPE:
|
d_value
|
Initial directional derivative.
TYPE:
|
new_d_value
|
New directional derivative after the step.
TYPE:
|
current_update_step_bfgs
|
Step size suggested by BFGS or optimizer.
TYPE:
|
t0
|
Start time of the epoch (used for timing).
TYPE:
|
xp
|
NumPy or CuPy module used for computation.
TYPE:
|
warnings
|
Warning string to be logged.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
create_static_background_from_nothing
¶
Generate an initial static background if none is provided.
| PARAMETER | DESCRIPTION |
|---|---|
static_background
|
Initial static background value or None.
TYPE:
|
probe
|
Probe wavefunction.
TYPE:
|
damping_cutoff_multislice
|
Maximum spatial frequency used.
TYPE:
|
data_pad
|
Padding to be applied.
TYPE:
|
upsample_pattern
|
Upsampling factor used.
TYPE:
|
default_float
|
Data type for output.
TYPE:
|
recon_type
|
Type of reconstruction ('near_field' or 'far_field').
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Initialized static background. |
create_probe_from_nothing
¶
Generate an initial probe guess when no valid probe is provided.
Depending on the input, this function either uses an aperture mask, computes a mean pattern from the dataset, or adjusts an existing mean pattern to generate a probe. It applies shifting, binning, padding, and scaling to produce a probe suitable for the specified reconstruction type.
| PARAMETER | DESCRIPTION |
|---|---|
probe
|
Input probe. If set to "aperture", the aperture mask is used. If None, the probe is generated based on the mean pattern.
TYPE:
|
data_pad
|
Padding size applied to the data.
TYPE:
|
mean_pattern
|
Mean pattern used to generate the probe if no probe is provided.
TYPE:
|
aperture_mask
|
Aperture mask used when probe is set to "aperture".
TYPE:
|
tilt_mode
|
Flag indicating if tilt mode is active.
TYPE:
|
tilts
|
Tilt values.
TYPE:
|
dataset
|
Measured dataset.
TYPE:
|
estimate_aperture_based_on_binary
|
Factor used to threshold the dataset for aperture estimation.
TYPE:
|
pixel_size_x_A
|
Pixel size in the x-direction in angstroms.
TYPE:
|
acc_voltage
|
Acceleration voltage in keV.
TYPE:
|
data_multiplier
|
Factor to scale the data intensity.
TYPE:
|
masks
|
Optional masks to apply to the mean pattern.
TYPE:
|
data_shift_vector
|
Vector indicating the shift to be applied to the data.
TYPE:
|
data_bin
|
Binning factor.
TYPE:
|
upsample_pattern
|
Upsampling factor applied to the pattern.
TYPE:
|
default_complex_cpu
|
Complex data type for CPU computations.
TYPE:
|
print_flag
|
Flag controlling verbosity.
TYPE:
|
algorithm
|
Identifier for the reconstruction algorithm.
TYPE:
|
measured_data_shape
|
Shape of the measured data.
TYPE:
|
n_obj_modes
|
Number of object modes.
TYPE:
|
probe_marker
|
Marker array for probe scenarios.
TYPE:
|
recon_type
|
Type of reconstruction ("near_field" or "far_field").
TYPE:
|
defocus_array
|
Array of defocus values.
TYPE:
|
Cs
|
Spherical aberration coefficient.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The generated probe as a complex array. |
generate_hermite_modes
¶
Generate Hermite polynomial-based probe modes from a main mode.
| PARAMETER | DESCRIPTION |
|---|---|
main_mode
|
The main probe mode.
TYPE:
|
n_herm_x
|
Max Degree of Hermite polynomials in x.
TYPE:
|
n_herm_y
|
Max Degree of Hermite polynomials in y.
TYPE:
|
default_complex
|
Complex data type to use.
TYPE:
|
xp
|
Numerical backend.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Stack of Hermite-based probe modes. |
apply_probe_modulation
¶
Apply defocus, aberrations, Hermite mode generation, and other modulations to the probe.
| PARAMETER | DESCRIPTION |
|---|---|
probe
|
Initial probe.
TYPE:
|
extra_probe_defocus
|
Defocus distance to apply.
TYPE:
|
acc_voltage
|
Accelerating voltage in keV.
TYPE:
|
pixel_size_x_A
|
Pixel size in x (Å).
TYPE:
|
pixel_size_y_A
|
Pixel size in y (Å).
TYPE:
|
aberrations
|
List of aberration coefficients.
TYPE:
|
print_flag
|
Whether to print info.
TYPE:
|
beam_ctf
|
Optional beam CTF to apply.
TYPE:
|
n_hermite_probe_modes
|
Number of Hermite modes in (y, x).
TYPE:
|
defocus_spread_modes
|
Defocus values to generate additional modes.
TYPE:
|
probe_marker
|
Probe assignment array for multi-scenario.
TYPE:
|
default_complex
|
Complex type.
TYPE:
|
default_float
|
Float type.
TYPE:
|
xp
|
Numerical backend.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Modulated probe array. |
prepare_main_loop_params
¶
Prepare main loop parameters for reconstruction.
This function adjusts scan positions, pads the object if necessary, handles subpixel corrections, and computes the electron wavelength based on the accelerating voltage.
| PARAMETER | DESCRIPTION |
|---|---|
algorithm
|
Identifier for the reconstruction algorithm.
TYPE:
|
probe
|
The probe array.
TYPE:
|
obj
|
The object array.
TYPE:
|
positions
|
Array of scan positions.
TYPE:
|
tilts
|
Array of tilt angles.
TYPE:
|
measured_data_shape
|
Shape of the measured data.
TYPE:
|
acc_voltage
|
Accelerating voltage in keV.
TYPE:
|
allow_subPixel_shift
|
If True, compute subpixel corrections (default is True).
TYPE:
|
sequence
|
Sequence of indices for positions (default is None, which uses full range).
TYPE:
|
use_full_FOV
|
If True, use full field-of-view adjustments (default is False).
TYPE:
|
print_flag
|
Verbosity flag (default is 0).
TYPE:
|
default_float_cpu
|
Float data type for CPU computations (default is np.float64).
TYPE:
|
default_complex_cpu
|
Complex data type for CPU computations (default is np.complex128).
TYPE:
|
default_int_cpu
|
Integer data type for CPU computations (default is np.int64).
TYPE:
|
probe_constraint_mask
|
Optional mask for probe constraints.
TYPE:
|
aperture_mask
|
Optional aperture mask.
TYPE:
|
extra_space_on_side_px
|
Extra padding (in pixels) to add to scan positions (default is 0).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
A tuple containing: - obj : ndarray The padded object array. - positions : ndarray Adjusted (rounded) scan positions. - int A placeholder zero (reserved for future use). - sequence : list The sequence of indices used. - wavelength : float Computed electron wavelength in angstroms. - full_pos_correction : ndarray Subpixel corrections for scan positions. - tilts_correction : ndarray Array of zeros with same shape as tilts (tilt corrections). - aperture_mask : ndarray or None The probe constraint mask or aperture mask if provided. |
prepare_saving_stuff
¶
Prepare folder and loss CSV for saving training logs.
| PARAMETER | DESCRIPTION |
|---|---|
output_folder
|
Directory for results.
TYPE:
|
save_loss_log
|
Whether to save loss values.
TYPE:
|
epoch_prev
|
Previous epoch index.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
print_pypty_header
¶
Print formatted header announcing start of reconstruction.
| PARAMETER | DESCRIPTION |
|---|---|
data_path
|
Path to the dataset.
TYPE:
|
output_folder
|
Directory where results are saved.
TYPE:
|
save_loss_log
|
Whether loss logging is enabled.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
save_current_checkpoint_obj_probe
¶
Save intermediate reconstruction data as checkpoints.
This function saves the current state of the object, probe, tilt corrections, scan positions, static background, and aberrations to disk. It is intended to allow resuming reconstruction from the last checkpoint.
| PARAMETER | DESCRIPTION |
|---|---|
output_folder
|
Directory where checkpoint files will be saved.
TYPE:
|
obj
|
The current object array.
TYPE:
|
probe
|
The current probe array.
TYPE:
|
tilts_correction
|
Correction values for tilt angles.
TYPE:
|
full_pos_correction
|
Sub-pixel correction values for scan positions.
TYPE:
|
positions
|
Scan positions array.
TYPE:
|
tilts
|
Tilt angles array.
TYPE:
|
static_background
|
Static background array.
TYPE:
|
current_probe_step
|
Flag indicating whether to save the probe.
TYPE:
|
current_obj_step
|
Flag indicating whether to save the object.
TYPE:
|
current_probe_pos_step
|
Flag indicating whether to save the scan positions.
TYPE:
|
current_tilts_step
|
Flag indicating whether to save the tilt angles.
TYPE:
|
current_static_background_step
|
Flag indicating whether to save the static background.
TYPE:
|
current_aberrations_array_step
|
Flag indicating whether to save the aberrations array.
TYPE:
|
aberrations_array
|
The current aberrations array.
TYPE:
|
beam_current
|
The current beam current array.
TYPE:
|
bcstep
|
Flag indicating whether to save the beam current.
TYPE:
|
xp
|
Numerical backend (e.g., numpy or cupy).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
print_recon_state
¶
Display current reconstruction progress including loss, optimization state, and updates.
| PARAMETER | DESCRIPTION |
|---|---|
t0
|
Start time of the epoch (Unix timestamp).
TYPE:
|
algorithm
|
Name of the loss or optimization algorithm used.
TYPE:
|
epoch
|
Current training epoch.
TYPE:
|
current_loss
|
Loss value at current epoch.
TYPE:
|
current_sse
|
Sum of squared errors.
TYPE:
|
current_obj_step
|
Whether the object is being updated.
TYPE:
|
current_probe_step
|
Whether the probe is being updated.
TYPE:
|
current_probe_pos_step
|
Whether the scan grid is being updated.
TYPE:
|
current_tilts_step
|
Whether tilt corrections are being updated.
TYPE:
|
current_static_background_step
|
Whether static background is being updated.
TYPE:
|
current_aberrations_array_step
|
Whether aberration coefficients are being updated.
TYPE:
|
current_beam_current_step
|
Whether beam current is being updated.
TYPE:
|
current_hist_length
|
Optimizer memory length (0=GD, 1=CG, >1=BFGS).
TYPE:
|
print_flag
|
Verbosity flag: 0 = silent, 1 = single-line print, 2 = verbose.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
try_to_gpu
¶
Convert all key reconstruction variables to GPU arrays if using CuPy.
| PARAMETER | DESCRIPTION |
|---|---|
obj
|
Object array.
TYPE:
|
probe
|
Probe array.
TYPE:
|
positions
|
Integer scan positions.
TYPE:
|
full_pos_correction
|
Sub-pixel scan grid correction.
TYPE:
|
tilts
|
Tilt values.
TYPE:
|
tilts_correction
|
Tilt corrections.
TYPE:
|
masks
|
Optional segmentation or region masks.
TYPE:
|
defocus_array
|
Array of defocus values per position.
TYPE:
|
slice_distances
|
Slice spacing in multislice simulations.
TYPE:
|
aperture_mask
|
Probe aperture mask.
TYPE:
|
dataset
|
Measured dataset.
TYPE:
|
load_one_by_one
|
Whether dataset is streamed from disk.
TYPE:
|
static_background
|
Static background array.
TYPE:
|
aberrations_array
|
Array of aberration coefficients.
TYPE:
|
beam_current
|
Beam current scaling factor.
TYPE:
|
default_float
|
Float precision dtype for casting.
TYPE:
|
default_complex
|
Complex precision dtype for casting.
TYPE:
|
default_int
|
Integer dtype for casting.
TYPE:
|
xp
|
Numerical backend (
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The same variables in GPU format (if using CuPy), with proper types. |
try_to_initialize_beam_current
¶
Initialize beam current array or pad if it's too short.
| PARAMETER | DESCRIPTION |
|---|---|
beam_current
|
Existing beam current values.
TYPE:
|
measured_data_shape
|
Shape of measured dataset.
TYPE:
|
default_float
|
Float type for the array.
TYPE:
|
xp
|
NumPy or CuPy.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Initialized or padded beam current. |
get_value_for_epoch
¶
Evaluate a list of values or functions at the current epoch.
| PARAMETER | DESCRIPTION |
|---|---|
func_or_value
|
List of fixed values or callables.
TYPE:
|
epoch
|
Current epoch number.
TYPE:
|
default_float
|
Float precision type.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Evaluated values. |
get_steps_epoch
¶
Evaluate step values for the current epoch.
| PARAMETER | DESCRIPTION |
|---|---|
steps
|
List of (multiplier, callable) or fixed values.
TYPE:
|
epoch
|
Current training epoch.
TYPE:
|
default_float
|
Float precision type.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
List of step values. |
lambda_to_string
¶
Extract lambda function source as a string.
| PARAMETER | DESCRIPTION |
|---|---|
f
|
Lambda function.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Extracted string source of the lambda. |
convert_to_string
¶
Convert parameter dictionary to string format, including lambda serialization.
| PARAMETER | DESCRIPTION |
|---|---|
dicti2
|
Original parameter dictionary.
TYPE:
|
strip_dataset_from_params
|
Whether to exclude 'dataset' key (default is True).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Dictionary with string values. |
string_to_lambda
¶
Convert stringified lambda expression to a Python function.
| PARAMETER | DESCRIPTION |
|---|---|
lambda_string
|
Lambda string to evaluate.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The resulting function or original string if evaluation fails. |
load_params
¶
Load parameter dictionary from a .pkl file.
| PARAMETER | DESCRIPTION |
|---|---|
path
|
Path to the .pkl parameter file.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Loaded parameters. |
string_params_to_usefull_params
¶
Convert string-encoded lambdas in parameter dictionary back to callables.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Parameter dictionary possibly containing lambda strings.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Updated dictionary with callables. |
save_params
¶
Save parameters to a .pkl file, optionally removing the dataset.
| PARAMETER | DESCRIPTION |
|---|---|
params_path
|
Output path for the parameter file.
TYPE:
|
params
|
Parameter dictionary to save.
TYPE:
|
strip_dataset_from_params
|
If True, remove the dataset entry.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
phase_cross_corr_align
¶
Align two FFT-transformed images using phase cross-correlation.
| PARAMETER | DESCRIPTION |
|---|---|
im_ref_fft
|
Reference image FFT.
TYPE:
|
im_2_fft
|
FFT of the image to be aligned.
TYPE:
|
refine_box_dim
|
Size of the interpolation box for sub-pixel alignment.
TYPE:
|
upsample
|
Upsampling factor for interpolation.
TYPE:
|
x_real
|
Real space x grid.
TYPE:
|
y_real
|
Real space y grid.
TYPE:
|
shift_y
|
Predefined shift in y (optional).
TYPE:
|
shift_x
|
Predefined shift in x (optional).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Shifted FFT of the second image. |
get_cupy_memory_usage
¶
Print current CuPy GPU memory usage statistics.
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
get_compute_batch
¶
Estimate the optimal compute batch size based on GPU memory usage.
| PARAMETER | DESCRIPTION |
|---|---|
compute_batch
|
Initial guess or default.
TYPE:
|
load_one_by_one
|
Whether data is streamed instead of fully loaded.
TYPE:
|
hist_size
|
History size for optimizers.
TYPE:
|
measured_data_shape
|
Shape of the input dataset.
TYPE:
|
memory_saturation
|
Proportion of GPU memory to use.
TYPE:
|
smart_memory
|
User-provided memory strategy.
TYPE:
|
data_pad
|
Padding applied to data.
TYPE:
|
obj_shape
|
Shape of the object array.
TYPE:
|
probe_shape
|
Shape of the probe array.
TYPE:
|
dtype
|
Data type string ('single' or 'double').
TYPE:
|
propmethod
|
Propagation method name.
TYPE:
|
print_flag
|
Verbosity.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Suggested batch size, load_one_by_one flag, and memory strategy. |
load_nexus_params
¶
Load reconstruction parameters from a NeXus (.nxs) HDF5 file.
| PARAMETER | DESCRIPTION |
|---|---|
path_nexus
|
Path to the .nxs file.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
Dictionary of extracted parameters. |
delete_dataset_from_params
¶
Delete the 'dataset' key from saved parameter file.
| PARAMETER | DESCRIPTION |
|---|---|
params_path
|
Path to the pickled parameters file.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
convert_to_nxs
¶
Convert saved PyPty reconstruction data to NeXus (.nxs) format.
| PARAMETER | DESCRIPTION |
|---|---|
folder_path
|
Directory containing saved reconstruction files.
TYPE:
|
output_file
|
Path where the NeXus file will be saved.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
None
|
|
pypty.se¶
getvirtualhaadf
¶
Compute a virtual HAADF image from a 4D-STEM dataset.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
Dictionary containing parameters including data path, scan size, plotting option, and output folder.
TYPE:
|
save
|
Whether to save the resulting HAADF image as a .npy file. Default is True.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
haadf
|
The computed virtual HAADF image.
TYPE:
|
get_aperture
¶
Generate a binary aperture mask based on the mean diffraction pattern.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Dictionary containing parameters including data path, data padding, plotting option, and bright threshold.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
params
|
Updated parameters dictionary containing the generated aperture mask.
TYPE:
|
create_binned_dataset
¶
Downsample a dataset by spatial binning and save it to a new file.
| PARAMETER | DESCRIPTION |
|---|---|
path_orig
|
The file path of the original dataset.
TYPE:
|
path_new
|
The file path to save the binned dataset.
TYPE:
|
bin
|
The binning factor to downsample the dataset.
TYPE:
|
compensate_pattern_drift
¶
Compensate for drift in diffraction patterns via phase correlation.
| PARAMETER | DESCRIPTION |
|---|---|
aperture
|
The binary aperture mask used for phase correlation.
TYPE:
|
patterns
|
The diffraction patterns to be compensated for drift.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
patterns
|
The compensated diffraction patterns.
TYPE:
|
get_virtual_annular_detector
¶
Create virtual detector signals from annular masks.
| PARAMETER | DESCRIPTION |
|---|---|
pypty_params
|
Dictionary containing parameters including data path, scan size, plotting option, and output folder.
TYPE:
|
inner_rad
|
Inner radius of the annular mask. Default is 0.
TYPE:
|
outer_rad
|
Outer radius of the annular mask. Default is 1.
TYPE:
|
save
|
Whether to save the resulting virtual detector signal as a .npy file. Default is False.
TYPE:
|
offset_x
|
X-offset for the annular mask. Default is 0.
TYPE:
|
offset_y
|
Y-offset for the annular mask. Default is 0.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
signal
|
The computed virtual detector signal.
TYPE:
|
pypty.vaa¶
plot_modes
¶
Plot the modes of a tensor.
| PARAMETER | DESCRIPTION |
|---|---|
ttt
|
A 3D or 4D array containing the modes to be plotted.
TYPE:
|
fit_aberrations_to_wave
¶
Calculate model positions based on step size and angle.
| PARAMETER | DESCRIPTION |
|---|---|
wave
|
complex real-space wave
TYPE:
|
px_size_A
|
|
acc_voltage
|
|
thresh
|
DEFAULT:
|
aberrations_guess
|
DEFAULT:
|
plot
|
DEFAULT:
|
ftol
|
DEFAULT:
|
xtol
|
DEFAULT:
|
loss
|
DEFAULT:
|
max_mrad
|
DEFAULT:
|
| RETURNS | DESCRIPTION |
|---|---|
|
list of fitted aberrations (in Angstrom) |
mesh_model_positions
¶
Calculate model positions based on step size and angle.
| PARAMETER | DESCRIPTION |
|---|---|
step_size
|
The step size for the model.
TYPE:
|
angle_rad
|
The angle in radians.
TYPE:
|
x
|
The x coordinates.
TYPE:
|
y
|
The y coordinates.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The model x and y coordinates. |
mesh_objective_positions
¶
Objective function for mesh optimization.
| PARAMETER | DESCRIPTION |
|---|---|
ini_guess
|
Initial guess for the optimization.
TYPE:
|
x
|
The x coordinates.
TYPE:
|
y
|
The y coordinates.
TYPE:
|
mesh_x
|
The mesh x coordinates.
TYPE:
|
mesh_y
|
The mesh y coordinates.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The sum of squared differences. |
get_step_angle_scan_grid
¶
Determine the step size and angle for a scan grid.
| PARAMETER | DESCRIPTION |
|---|---|
positions
|
The measured positions.
TYPE:
|
scan_size
|
The size of the scan grid.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The step size and angle in degrees. |
get_affine_tranform
¶
Calculate the affine transformation matrix from positions.
| PARAMETER | DESCRIPTION |
|---|---|
positions
|
The measured positions.
TYPE:
|
scan_size
|
The size of the scan grid.
TYPE:
|
px_size_A
|
Pixel size in angstroms.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The deformation matrix. |
add_scalebar_ax
¶
Add a scale bar to a given axis.
| PARAMETER | DESCRIPTION |
|---|---|
ax
|
The axes to which the scale bar will be added.
TYPE:
|
x
|
The x-coordinate of the bottom left corner of the scale bar.
TYPE:
|
y
|
The y-coordinate of the bottom left corner of the scale bar.
TYPE:
|
width
|
The width of the scale bar in pixels.
TYPE:
|
height
|
The height of the scale bar in pixels.
TYPE:
|
x_t
|
The x-coordinate for the text label.
TYPE:
|
y_t
|
The y-coordinate for the text label.
TYPE:
|
px_size
|
The pixel size in the same units as the width and height.
TYPE:
|
unit
|
The unit of measurement for the scale bar.
TYPE:
|
outputlog_plots
¶
Plot log file data from PyPty.
| PARAMETER | DESCRIPTION |
|---|---|
loss_path
|
Path to the PyPty CSV file.
TYPE:
|
skip_first
|
Number of initial iterations to skip (default is 0).
TYPE:
|
plot_time
|
If True, a second x-axis showing time in seconds will be added on top of the plot.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
List of plotted figures. |
radial_average
¶
Calculate the radial average of a 2D array.
| PARAMETER | DESCRIPTION |
|---|---|
ff
|
The input 2D array.
TYPE:
|
r_bins
|
The bin size for the radial average.
TYPE:
|
r_max
|
The maximum radius for averaging.
TYPE:
|
r_min
|
The minimum radius for averaging.
TYPE:
|
px_size_A
|
Pixel size in angstroms.
TYPE:
|
plot
|
If True, the radial average will be plotted (default is True).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The figure containing the plot if |
complex_pca
¶
Perform PCA on complex data.
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The input data array of shape (N_y, N_x, N_obs).
TYPE:
|
n_components
|
The number of principal components to retain.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The reduced data array of shape (N_y, N_x, n_components). |
complex_array_to_rgb
¶
Convert a complex array to RGB format.
| PARAMETER | DESCRIPTION |
|---|---|
X
|
The input array of complex numbers.
TYPE:
|
theme
|
The color theme, either 'dark' or 'light' (default is 'dark').
TYPE:
|
rmax
|
Maximum absolute value for normalization (default is None).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The RGB representation of the input array. |
plot_complex_modes
¶
Plot complex modes in RGB format.
| PARAMETER | DESCRIPTION |
|---|---|
p
|
The input array of complex modes.
TYPE:
|
nm
|
The number of modes to plot.
TYPE:
|
sub
|
The number of rows for the subplot layout.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
|
The figure containing the plotted complex modes. |